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Abstract 


lliis document describes a common subset of selected rocitities available in Maclisp and its 
derivatives: PDP-10 and Multics Maclisp, Lisp Machine Lisp (Zetalisp), and NIL. Ilie object of 
this document is to aid people in writing code which can run compatibly in more than one of 
these cnvironmenla. 
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Introduction 


1. Introduction 

IJ Compatibility 

This manual is about compatibility between the PDP*10 and Multics dialects of Maclisp, and 
the Maclisp derivative Lisps, Lisp Machine Lisp, and NIL 

Believe it or not, it really is possible to write code that runs in all of these Lisp dialects. It 
is not always a completely painless thing to do, but with a tittle bit of care it is pt^ble to write 
reasonable code that runs in many places, and that doesn’t offend everyone who tries to read it, 

The biggest stumbling block to writing code that ru is in a Lisp dialect other than the one 
you arc most familiar with is the fact each of these Lisps has grown a different set of additional 
features since the original Maclisp Reference Manual was written in 1974. How arc you supposed 
to be able to restrain yourself from using all the winning new features that tltc implementors of 
your dialect have given you? 

Well, unfortunately, you are going to have to avoid some of them. After all, some are 
probably impossible to implement everywhere, On the other hand, some of them arc so useful 
that they have already migrated to all of the places you arc planning to move your code. Those 
arc the features that arc documented in this manual. 

1.2 Conventions 

The symbol will be used to indicate evaluation in examples, lliius, when you sec “too 
=> nil", this means the same thing as "the result of evaluating fo6 is ‘<or would have been) nil". 

The symbol "»=>" will be used to indicate macro expansion in examples. Thus, when you 
sec "(foo bar) >=> (aref bar 0)", this means the same thing as "the result of macro-expanding 
(foo bar) is (or would have been) (aref bar 0)". 

Most numbers shown arc in octal (base eight). Numbers followed by a decimal point arc in 
decimal (base ten). Despite growing sentiment in favor of decimal as the default base for Lisp 
reading, it is still tltc case that most of the Lisps we arc concerned vv i read numbers in octal by 
default; the sole exception at this time is NIL. 

Symbols arc consistently written in lower case. This is because on Multics, most symbols have 
lowercase printnames, and case translation is not done by default on input. In the other 
implementations, where most symbols have uppercase printnames, lowercase characters are 
translated to uppercase on input, so a symbol typed in lowercase will always be read correctly 
everywhere. 
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2. Backquote 

I'hc backquote facility defines two reader macro characters, backquote C"", ascii 140) and 
comma ascii 54). Ilicsc two macro characters can be used together to abbreviate large 
compositions of functions like cons, list, list* (page 19) and append, it is typically used to 
specify templates for building code or oUter list structure, and often finds application in the 
construction of Lisp macros. 

Backquote has a syntax similar to that of quote ("'**, ascH 47). A backquote is followed by a 
single font). If the form does not contain any use of the comma macro character, then the form 
will simply be quoted. For example: 

'(a b c) - (quota (abc)) ■ *(abc) 

The comma macro character may only be used within a form following a backquote. Comma also 
has a syntax like that of quote, 'fhe comma is followed by a form, and that form is evaluated 
even though it is inside the backquote. For example: 


'(.a b 

c) ■ 

(cons a (quote (b c))) 


■ 

(cons a '(b c)) 

'(a ,b 

c) * 

(list* (quote a) b (quote (c))) 


Ml 

(list* 'a b '(c)) 

*(a b 

.c) - 

(Til St (quote a) (quote b) c) 


a 

(list 'a 'b c) 


*(a . ,rest) - (cons (quote a) rest) 

- (cons ‘a rest) 

In other words, all the compommte of the backquoted expression are quoted, except those 
precccdcd by a comma. 'Ilms, one could write the common macro push using backquote by 
proceeding from the standard defiiiiition 

(defun push macro (form) 

(list 'setq (caddr form) 

(list 'cons (cadr form) (caddr form)))) 


to 


(defun push macro (form) 

'(setq ,( caddr form) (cons ,(cadr form) ,( caddr form)))) 

Note how the code to build the macro’s output code begins to bok more like the output code 
itself. In fact, with a use of let, we can go all the way to 

(defun push macro (form) 

(let ((datum (cadr form)) 

(list ( caddr form) ) ) 

'(setq ,1ist (cons , datum ,list)))) 

iind produce very legible cmie. An even belter method ft»r definutg nutcros is defmacro (chapter 
5, page 10). 
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Backquote 


Qockquotc expands inU) forms that call cons, list, list* or whatever other hinctions it deems 
appropriate for the task of constructing a form that looks like Ute one following the backquute, 
but with (he values of the forms following the commas substituted in. 


Since backquote's contract is specified not in terms of the code that it expands into, but 
rather in terms of what that code produces when evaluated, assumptions should not be made 
about what the code might look like. Ihe backquotc expansions shown in this section are only 
possible expansions; it is not guaranteed that this is (he way they will expand in any particular 
implementation. 


if a comma inside a backquote form is followed by an "at” sign ascii 100), then the 

form following the should return a list. (On Multics, since the default line kill character is 

@, the user may need to type \@ in ord^r to get lisp to read a @.) Backquote arranges that 
the elements of that list will be substituted into the resulting list structure. Frequently this 
involves generating a call to the function append. For example: 


'(.9a b c) 


(append a (quote (b c))) 
(append a '(b c)) 


'(a ,9b c) 


(cons (quote a) (append b (quote (c)))) 
(cons 'a (append b ’(c))) 


‘(a b ,0c) 


(list* (quota a) (quota b) c) 
(list* 'a 'b c) 


Similar to following the comma by an atsign is following the comma by a dot (".”, ascii S6). The 
dot is a declaration to backquote telling it that tire list returned by the form following the is 
expendable. Ihis allows backquote to produce code that calls functions like nconc that rplac the 
list 


Backquote examines the forms following the commas to see if it can simplify the resulting 
code. For example: 

‘(a b . ,(cons x y)) * (list* (quote a) (quota b) x y) 

- (list* 'a 'b X y) 

'(a 3 ,b c ,17) (list* (quote a) 3 b (quota (c 17))) 

^ (list* 'a 3 b '(c 17)) 

'(a ,8b .0h11) ■ (cons (quote a) b) 

■ (cons 'a b) 

'(a ,.b ,9(nconc c d)) » (cons (quote a) (nconc b c d)) 

« (cons ‘a (nconc b c 9)) 

'Ihcsc cxarnplcs should convince the user that he really cannot depend on what the code that 
backquote expands into will look like. A simple-minded backquote might expand (,@a ,@nil) 
into (append a ’nil), but this cannot be used as a reliable way to copy a list since a sophisticated 
b.'ickquoto can optimize the copying away. 
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It is sometimes usefVil to nest one use of backquote within another. This might happen when 
the user is writing some code that will cons up some more code that will in turn cons up yet 
more code, llic usual example is in writing macro deflning macros. When this becomes necessary 
it is sometimes difficult to determine exactly how to use comma to cause evaluation to happen at 
the correct times. The following example exhibits ail the useAii combinations; 

••(a ,b ,.c ,'.d) 

- (Tist 'Htit* "a 'b c (list 'quota (list d))) 

When evaluated once this yields; 

(list* 'a b <c-at-t1ma-l> '(<d-8t-t1raa-l>)) 

Which when evaluated yields; 

(a <b-st-t1ma-2> «c-at-t1m#-l>-at-t1nia-2> <d-at-t1ma-I>) 

Thus '*” means never evaluate, means evaluate only the second time, means evaluate both 
times, and means evaluate only the first time. 
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3. Sharpsign 

The Lisp reader’s syntax can be extended with abbreviations introduced by sharp sign 
ascii 43). These take the general form of a sharp sign, a second character which identifies the 
syntax, and following arguments Certain abbreviations allow a decimal number or certain special 
’'modifier" characters between the sharp sign and the second character, (On Multics, since tlie 
default erase character is # , it may be necessary to type \ # in order to get lisp to read a 4^ ,) 

List of # macro abbreviation!; 

0/char 

reads in as the number which is the character code for the character char. For 
example, 0/a is equivalent to 14 1 but clearer in its intent. This is die recommended 
way to include character constants in your code. Note that the slash cause's this 
construct to be parsed correctly by the Bmacs and Zwei editors. 

» 

As in strings, upper and lower-case letters are distinguished after 0/. Any character 
works after 0/, even those that arc normally special to read, such as parentheses. 
Even non printing characters may be used, alUiough for them # \ is preferred. 

0\mme 

reads in as the number which is the character code tor the non-printing character 
symbolized by name. /V large number of character names are recognized; these are 
documented below. T'ne abbreviations cr for return and sp for space arc accepted 
and generally preferred, since these characters arc used so frequently, The mics for 
reading name arc die same as those for symbols; the name must be terminated by a 
delimiter such as a space, a c<«’ riage return, or a parenthesis, 

0''char 

generates Control-c/iar. Thus 0 ''char always generates the character returned by tyi if 
the user holds down the control key and types char, 

0'form 

is an iibbrcviation for (function fomt). form is the printed prepresentation of any 
objc'ct, This abbreviation can be remembered by analogy with the * macro-character, 
since the function and quote special forms are somewhat analogous, 

0,/orm 

evaluates fonn (the printed representation of a Lisp form) at read time, unless the 
compiler is doing the reading, in which case it is arranged that form will be evaluated 
when the compiled output file is loaded. This is a way, for example, to include in 
your code complex list-structure constants which cannot be written with quote. Note 
that the reader docs not put quote around the result of the evaluation. You must do 
this yourself if you want it, typically by using the ’ macro-character. An example of a 
case where you do not want quote around it is when this object is an clement of a 
constant list. 

0 . fonn 

evaluates farm (the printed representation of a lisp form) at read time, regardless of 
who is doing the reading, This iibbrcviation w'oiild be used to supply constiint 
piiramcters to the compiler. For example, a prognini might contain 4^, PI, ratltcr 
then 3.14159, 
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Hf Onumber 

reads number in octal regardless of the setting of ttMM, 

# radii^number 

reads number in radix radix regardless of the setting of ibtso. radix must consist of 
only digits, and it is read in decimal. 

For example, #3R102 is another way of writing 11, and #11R32 is another way of 
writing 35. In Maclisp, siipradccimal bases may be used if number is preceded by -f 
or - ; (status is temporarily modified to make this work. 

^ * feature 

This abbreviation provides a read-time conditionalization fitcility. It is used as 
iijr ^feature fortn, If feature is a symbol, then this is read as fom if (status feature 
feature) is true. If (status (nature feature) is nil, then tliis is read as whitespace. 
Alternately, feature may be a b(H>lcan expression composed of and, or, and not 
operators and symbols representing items which may appear on Uic (status features) 
list, (or lispm amber) represents evaluation of die predicate (or (status feature 
lispm) (status feature amber)) in the read-time environment. 

For example, d 4 lispm form makes form exist if being read by the Usp machine. 
# ^ (or lispm nil) form will make form exist on cither the Fisp machine or in NIL. 
Note that items may be added to the (status features) list by means of (sslatus 
feature feature)^ thus allowing the user to selectively interpret or compile pieces of 
code by parameterizing this list 'Hie most common features checked for using # <f 
are: lispm (present on lisp Machines), Maclisp, NIL, Multics, ITS, TOPS-20 and 
PDP10. 

Sec also section 11.4.1, page 62 for a more general discussion of conditionalization. 

# -feature form 

is equivalent to # 4 (not feature) form, 

0Mform 

is equivalent to # 4 Maclisp form. 

MQform 

is equivalent to # 4 Nsptn form, 

MHform 

is equivalent to # 4 NIL form. 
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flic following are ihe recognized special character names, with their synonyms. ITicsc names can 
be used after a to get the character code for that character. 


backspace 

bs 

tab 


nawitne 


Ifnefeed 

If 

return 

cr 

formfeed 

ff 

attmode 

alt 

space 

•P 

vt 


null 


help 


delate 

rubout 


Certain of these character groupings may overlap in some implementations, For example, on 
Multics. help is simply the 7 character, newline will generally be equivalent to either return or 
linefeed, as appropriate for the host operating system. 


Ml iMAClKK ;SIIAKI»M ?0 


.’l-Jlil -III 




Rxtcndcd I>cflin 


8 


Maclisp Extensions 


4. Extended Defun 

d«f un Special Form 

defun is the usual way of defining functions. It still works the way it always has, but 
several improvements have been added over the years. 

A defun Form looks like: 

(defun mme lambda-list 
body . . .) 

As in the past, name can be a symbol which is to be defined as a function. Alternatively, 
name can be a list of the Form (symbol property). This arranges to give symbol a property 
property oF the function, rather than defining some symbol to be that Function. In other wordi 
after a deftin like 

(defun (foo bar) (x) 

(cons X x)) 

it would be the case that 

(funcall (get ’foo ’bar) 34) »> (34 . 34) 

In tfic simplest case lambda-list is a list of variables to bind to the arguments to the Function; 
this is as it h:?s always been. In addition, the keywords Aoptional, &rest and Aaux are allowed 
to appear there, ('Htus tlicsc arc no longer valid variable names, but nobody seems to have been 
inconvicnccd by this.) 'Ilieir meanings are as Follows; 

Aoptional All of the variables Following the ftoptlonal keyword (and up to the next A- 
keyword) are optional. Thus a lambda-list oF the form 

(a b &opt1ona1 c d) 

mc,’<t;s that the function may be passed From two to Four arguments, a and b are 
called required arguments, c and d arc called optional arguments (not surprisingly). 
If an optional argument is not passed in by the caller, then the corresponding 
variable will be bound to nil. If some other default value is desired, then that 
value may be specified as Follows; 

(a b &opt1ona1 (c ’default) (d b)) 

Thi',^ will bind c to the symbol default if the iunction is passed only two 
arguments. If tlic fttnclion is passed less than four, then d will be bound to the 
second argument. This is because the variables arc bound in sequence, so their 
default values may refer to the values of variables already bound. 

It is also possible to find out whether an optional variable was supplied. 'ITie bvl 

(a b ftoptional (c 'default c~p)) 

will bind the varial)It c-p to t if the function was passed three arguments (i.e.. an 
argument was supplied for c). nil if it was passed only two. 
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&ro8t lilts keyword must be followed by exactly one variable called the rest variable. 

&rest must also appear ({fltfr any required or optional variables. Iltc rest variable 
will be bound to a list of the remaining arguments Utat were passed to die 
function, For example; 

(a b &r««t c) 

is the lambda-lis* ,o use for a hinction that accepts two or more arguments, lire 
variable c will be bound to a list of the arguments ftom the third one on. 

(a b &opt|ona1 (c 0) ftrasi d) 

would specify that the function takes two arc more arguments. If called on 
exactly two arguments, c will be bound to 0 and d will be bound to nil. If 
called tm three or more arguments, c will be bound to the third argument and d 
will be bound to a list of tiic fourth through last argument. 

In the lisp Miichine implenicntation, tlie rest variable will be bound to a stack 
allocated list that is only valid during the invocation of that hmetion, Ihis means 
that tbc function should not incorporate tliis list into any pennanent data-structurc; 
it should use a copy of the list instead, 

In Nil,, the rest variable will be bound to a vector which may be stack allocated. 
Ilrestl instead of ireat selects a list. Unfortunately, Aresll Is only rccognircd In 
PDP IO Maclisp and NIL, 

&aax Following the keyword &nux arc some more variables called auxiliary variables. 

&aux must follow all required and optional variables and the rest variable if it is 
given, Auxiliary variables do not correspond to arguments to the function at all, 
they arc simply local variables that are bound scqucntually after the argument 
variables. Lor example; 

(1 goptional (a t) &aux (1«n (length I)) tern) 

is the lambdadist of a one or two argument ftmctlon, b will be bound to t If the 
second argument is not given, then ten will be hound to the length of Uic list 
that was tlic first argument, and tern will be bound to nil (presumably for use 
later on.) 

In Miiclisp, functions with optional or rest variables will be implemented using the texpr 
mechanism, In these implementations it may be nccessiiry to declare tlicsc functions as Icxprs in 
order to assure proper compilation. 

Ihc syntax 

(defun mne macro (form) 

. •) 

Is still undcistood as a way to define a macro, but the new macro defining mjicro dofmacro is 
now tlic prefered way to do so, defmacro is documcmed in chapter S, page 10, 
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5. Defmacro 

dtfMtcro Macro 

defmacro is a macro-defining macro which allows one to define macros in a more natural 
or functional way. 

If we want to define the first macro such that (first x) is equivalent to (car x), we could 
do 

(dafun first macro (x) 

( list 'car (cadr x))) 

or, using barkquute (page 2) 

(defun first macro (x) 

'(car .(cadr x))) 

Just as backquotc makes constructing list structure less cumbersome, defmacro allows us to 
access the "arguments" to a macro in a much cleaner manner, 'lire first macro looks like 

(defmacro first (1) 

•(car ,1)) 

when define'! with defmacro. 

In general, the argument list to a macro defined with defmacro is a pattern to be matched 
against the body of the macro call, 'lire symbols in the pattern will be bound to the 
corresponding components, and then the body of the macro evaluated, the same as is done for an 
ordinary macro. 'Ilrat is, for tire macro call (first (get 'frob 'elements)), the pattern (I) is 
matched against ((get 'frob 'elements)), and I gets bound to the form (get 'frob 'elements). 

lire macro push, which is defined on page 2 as 

(defun push macro (form) 

(let ((datum (cadr form)) 

(list ( caddr form) ) ) 

'(setq .list (cons .datum .list)))) 

could be defined with defmacro by 

(defmacro push (datum list) 

'(setq .list (cons .datum .list))) 

Macros, and thus defmacro, arc u.scful for defining fornrs which provide syntax for some 
kind of control stnicturc. For example, somcoric might want a limited iteration construct which 
increments a variable by one until it exceeds a limit (like the FOR statement of tire BASIC 
language). One might want it to look like 

(for a 1 100 (print a) (print (* a a))) 

I'o got this, one could write a macro to translate it into 
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(do a 1 (U a) {> a 100) (print a) (print (• a a))) 

A macro to do this could be defined with 
(dafun for macro (x) 

'(do .(cadr x) .(raddr x) (U ,(cadr x)) 

(> .(cadr x) .(cadddr x)) 

,0(cddddr x))) 

Alternatively, for could be defined with defmacro: 

(defmacro for (var lower upper . body) 

‘(do ,var .lower (1^ ,var) (> .var .upper) 

.Obody)) 

If a pattern is not sufficient, or if a more function-like interface is desired, the argument list 
to defmacro may contain certain &-keywords, 'fhese arc analogous to tire &-kcywords iKccpted 
by defun (sec page 8). In Uus case, the argument list should nol have a dotted end (like the lor 
example), allltough die components loay fficmscivcs be patterns. 

Aoptional denotes the start of optional "arguments" to the miicro, Each followittg parameter 
is tlien of tlle form vambte, (variuble), (variable default), or (variable default presenhp). default 
is a ibrm to be evaluated to provide a value of no corresponding "argument" is present in the 
cali. present-p is a variable; it will be bound to nil if no argument is present t otherwise. For 
example, 

(defmacro pr int-1n~radtx (x ftoptional (radix 10.) (•nopoint? t)) 
'(let ((base , radix) (*nopoint ,*nopoint?)) 

(print ,x))) 

If variable is a pattern, then the first fonn is disallowed byccausc it is syntactically ambiguous. 
'Ihc pattern must be enclosed in a singleton list. Note; in some implementations, if variable is a 
pattern, default may be cvaluatccf more than once. 

&rest says Uiat tlie following item should be matched against Utc rest of the call. 'ITiat is, the 
argument list (&rest items) is equivalent to tlic argument list items, and the argument list for for, 
(var lower upper , body), could have been written as (var lower upper irest body). &rest 
may be easier to read than a dotted list, and it allows one to use &aux. 

&aux has nothing to do with pattern matching. It should come at tlic end of the pattern 
(which tluis cannot be a dotted list), and may be followed by one or more variable binding 
spccificatioiss, of tlic form variable or (variable value). 'Ihc variable will be bound to the specified 
value, or nil. 

&body is iJcntical to &rest, and in certain implementations may leave some information 
around for other progiams to use to decide on how that form should be indented. Ihc for macro 
should be delincd with &body in preference to &rest. 

'Ihc Aoptional variable bindings arc performed sctiucniually, Thus something like 

(definacro foo (a ftoplional (b a)) ..,) 

will define a macro that when called with only one argument will bind both a and b to that 
argument. When called with two arguments a will be bound to the fust arguineivi, and b will he 
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bound to the second. 

lltc macro dolist (page 23) is defined such that 
(dollst (var Usi) form- 1 form-2 

steps var over the elements of list, evaluating all of the form-i each time (sort of like mape). It 
could be defined wi^h defmacro by 

(defmacro dolist ((var Mst) &body forms 

&aux (llst-var (gensym))) 

'(do ((, llst-var ,11st (edr , llst-var)) 

( ,var)) 

((null , llst-var)). 

(setq ,var (car , llst-var^) 

.gforms) ) 
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6. Other Definition Facilities 

dnfvnr variable (intf] [documentation] Special Form 

defvar is the recommended way to declare the use of a global variable in a program. 
The form 

(defvar variable init) 

placed at top leVel in a file b roughly equivalent to 

(declare (special variable)) 

(or (boundp ’variable) 

(setq variable init)) 

If the init form is not given, then defvar does not try to initialize the value of the 
variable, it only declares it to be special, 

documentation is ignored in most implementations, although it is a good idea to supply it 
for the benifit of those implementations that make use of it. It should be a "string” (see 
page 63). 

dafeonat variable [/>i/r] [documentation] Special Form 

defconst is similar to defvar expect that if init is given, then variable is aivvays set to 
have that value, regardless of whether it is already bound. The idea is that defvar 
declares a global variable, whose value is initialized to something but will then be 
changed during the running of the program. On the other hand, defconst declares a 
constant, whose value will never be changed by the program, only by changes to the 
program, defconst always sets variable to the specified value so that if you change your 
mind about what the constant value should be, and then you evaluate the defconst form' 
again, variable will get set to the new value. 

aval -when times-list forms... Special Form 

eval-when is used to specify precisely what is to happen to the containing forms. An 
eval-when form must appear at top level in a file, times-list can contain any combination 
of the symbols eval, compile and load. 

If eval is in times-list, then when the interpreter evaluates the eval-when form each of 
the forms will be evaluated, If eval is not present, then the forms will be ignored in the 
interpreter. I1ie return value is not guaranteed to be anything in particular. 

If compile is in times-list, tlien when the compiler comes across the eval-when form at 
compile-time, it wilt evaluate each of the forms right then and there. 

if load is in times-list, then when the compiler comes across the eval-when form in the 
file, it will continue process the fonns as if they appeared at top level in the file. Ilius 
the result of compiling die forms will be pUtced into the compiler output file so that they 
may be loaded later. 

Examples: 
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(•«a1-when (eval compile) 

(satsyntax /" 'macro ’hack-strings) 

(defun hack-strings () 

...)) 

Iliis will fool with the syntax of doubicquotc at run-time and compilc-time (presumably to 
allow the rest of the file to be read in praperly), but when the file is compiled and 
loaded the syntax of doublequote will be unchanged, and the function hack-stritigs will 
not be defined. 

(oval-when (aval) 

(dafun foo (frob) 

(and (atom frob) (barf)) 

(car frob))) 

(aval-ahan (compile) 

(dafun foo macro (x) 

(list 'car (cadr x)))) 

'niis will define foo as a paranoid error checking function when the program is being run 
interpreted, but will arrange to define foo as a macro at compile-time so that it will 
compile just like car. When the compiled file is loaded foo will not be defined at all. 

(aval-when (aval compile load) 

(defprop frobulata f robulate-macro macro) 

(defun frobulata-macro (x) 

...)) 

Iliis is a way to define a macro by hand in Maclisp to be present whenever the file is 
being run or compiled. 
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7. Setf 

••tf Macro 

setf provides a general mechanism for modifying the components of arbitrary Lisp objects. 
A setf form looks like: 

( self reference form) 

llie setf form expands into code to evaluate form and then modify some Lisp object such 
that the form reference would evaluate to the same thing. For example; 

(setf (car x) 47) ■■> (rplaca x 47) 

(self (cadr. x) nil) ■>> (rplaca (edr x) nil) 

(setf (get a 'xip) ’foo) ■■> (putprop a 'foo ‘tip) 

(setf (arraycall t a 1) t) ■■> (store (arraycall t a 1) t) 
(setf (symeval foo) bar) -■> (set foo bar) 

(setf foo bar) ■■> (setq foo bar) 

'llic order in which form and any forms found in reference arc evaluated is not guaranteed 
in any but the PDF- 10 Maclisp ap4 NIL implementations of setf. Neither is the value 
returned by the code setf expands into guaranteed in any way. 

setf also knowns how to perform macro expansions of any reference it doesn't recognize. 
$0 if first is a macro defined to expand as 

(first foo) (car foo) 

then 


(setf (first foo) t) "■> (rplaca foo t) 

self's ability to expand macro forms makes it indispensable when using the defstruct macro 
(page 26). 

Several other common macros arc defined to expand into code that includes a setf form, All 
these other macros share the property with setf that in some implementations they arc liable to 
evaluate their various sub-forms in an order other than the one they were written in. in some 
cases you even run the risk uf having some sub-form evaluated more that once. 

push Macro 

push is defined to expand roughly as follows: 

(push frob reference) 

= => (setf reference (cons frob reference)) 

Ihe qualifications about order of evaluation given for setf apply to push also; 
additionally, only the P!)P-10 and NIL implementations guarantee tliat hums in reference 
will not bo evaluated multiple times. 
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pop is defined to expand roughly as follows; 

(pop reference) 

■ »> (progl (car reference) 

(s«tf reference (edr reference))) 

(progl is explained on page 2S.) 

'Ilic qualifications given for puiih about order of evaluation and multiple evaluation apply 
to pop also. 
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8. New Functions and Special Forms 

litis chapter documents a number of new functions and special forms that have been added 
to the Maclisp language. 

Although many of the functions documented here are shown shown as being functions, there 
is no guarantee that any particular Lisp actually implements them that way, rather than as macros. 

8.1 Bit Hacking 

All of the functions in this section optitait on integers of any size in Lisp Machine Lisp, but 
only on hxnums elsewhere. Remember that all the integers shown here are in octal. 

8.1.1 Boolean Operations 

'fhe following functions could be (and often are) implemented in terms of the boole function. 
Their use tends to produce less obscure code. 

logand &rcst args 

Returns the bit- wise logical and of its arguments. At least two arguments are required. 
Examples: 

(logand 3456 707) -> 406 

(logand 3456 -100) » 3400 

loglor Arest args 

Returns the bit-wise logical inclusive or or its arguments. At least two arguments are 
required. 

Example: 

(logior 4002 67) -> 4067 

togxor &rest args 

Returns the bit-wise logical exclusive or of its arguments. At least two arguments are 
required. 

Example: 

(logxor 2531 7777) -> 5246 


lognot number 

Returns the logical complement of number. 'Iliis is the same as logxor'ing number witit 

- 1 . 

Example: 

(lognot 3456) => -3457 
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8.1.2 Byte Manipulation 

Several functions arc provided for dealing with an arbitrary-width field of contiguous bits 
appearing anywhere in an integer (in Maclisp, this is restricted to a fixnum). Such a contiugous 
set of bits is called a byle. Note that the tenn byff is not being used to mean eight bits, but 
rather any number of bits within an integer. 1’hese functions use numbers called byte spec(fien to 
designate a specific byte position within any word, Byte specifiers arc fixnums whose two lowest 
octal digits represent the size of the byte, and whose higher octal digits represent the position of 
the byte within a number, counting from the right in hits. A positi,m of zero means that the 
byte is at the right end of the number. For example, the byte-specifier 0010 (i.e., 10 octal) 
refers to tlie lowest eight bits of a word, and the byte-specifier 1010 refers to the next eight bits. 
These byte-specifiers will be stylized below as ppss. The maximum reasonable values of pp and sa 
are dictated by the Lisp implementation, except of course ss may not "overflow" into the pp field, 
so may not exceed 77 (octal). 

Idb ppss num 

Returns the byte of num specified with the byte-specifier ppss, as described above. 

Example: 

(Idb 0306 4567) -> 66 

dpb byle ppss num 

Returns a new number made by replacing the ppss byte of num with byte. 


8.1.3 Testing 

bit-taat X y 

Returns t if any of the bits in jt and y intersect; that is, if their logand is not zero, bit- 
test could be (and sometimes is) defined as a macro such that 

(bit-test X y) -■> (not (zerop (logand x >*))) 


8.2 Predicates 

flanimp x 

Returns t if x is a fixnum. This com sponds to a typep of fixnum. 
Examples: 

(fixnuntp 1) ■> t 

(flxnump (oxpt 269. 269)} -> nil 


flonump X 

Returns t if x is a flonum.. 'I'his corresponds to a typep of flonum. 

Examples; 

(flonump 3.14) »> t 

(flonump 17) »> nil 

Note that this is the same as floatp in most Lisps, which have only one type floating- 
point representation. In Lisp Machine Lisp however, there are sonte kinds of flttating 
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point numbers (hat are not of type flonum. Nonump will return nil for these objects. It 
is probably the case that code that is trying to be compatible should use floatp in 
preference to either (Idnump or (eq (typep x) Honum). 

•rrayp x 

Returns t if x is an array, Note that some Lisps implement certain kinds of objects as 
arrays; for example, PDP-IO Maclisp file objects are arrays, and Usp Machine Lisp 
utilir^es arrays for. most structures defined with defstruct (page 26). 

•vanp integer 

Returns t if integer is even, nil otherwise. Iliis complements (he oddp fimetion which 
Usp provides. 

<■ &rest args 

<m requires at least two arguments. If any argument is greater than (he next argument, 
it returns nil, otherwise it returns t. In Maclisp, args should consist of cither all fixnums 
or all flonumi 

>■ Arest args 

Similar to < ■ . 

fboundp symbol 

fboundp returns nil if the symbol symbol in not defined as a function or special form. It 
returns something non*nil if symbol is defined. The exact nature of (he non-nil object 
varies from implementation to implementation. 

It is not defined what fboundp returns if symbol has an autoload property and is 
otherwise undefined. 

8.3 Lkts 

list* Arest args 

list* cr«i/atcs what some people call a "dotted list". 

(list* 'foo 'bar ’baz) ■> (foo bar . baz) 

(list* 'foo ’bar) «> (foo . bar) 

(list* 'foo) ■> foo 

list* makes certain unwieldy compositions of the cons function somewhat easier to type; 

(list* 1234) 
is the same as 

(cons 1 (cons 2 (cons 3 4))) 
naks-llst length 

make 'list creates a list of nils of length length. Fxamplc; 

(make-list 3) => (nil nil nil) 
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nth n list 

(nth n Ust) returns the «’th element of U%t, where the zeroth element Is the car of the 
list, If n is larger than the length of the list, nth returns nil. Examples; 

(nth 2 '(zaro on* two thrat)) ■> two 
(nth 0 ‘(a b c)) •> a 


nthedr n list 

(nthedr n list) edrs lisi n times, and returns the result. If n is larger than the length of 
the list then nil is returned. Examples; 

(nthedr 3 '(q w a r t y)) ■> (r t y) 

(nthedr 0 '(a t a o i n r)) ■> (a t a o i n r) 

Note that 

(nth n I) 

is the same as 

(car (nthedr n /)) 


8.4 Variables 

l#t Special Form 

(lat ((yarl val-l) (var^Jf val-2) ...) 
form-1 
form-2 
■•) 

binds varl to tltc value of ml- 1, var-2 to the value of ml-2 etc,, and evaluates each of 
tile fomi-i in that binding environment. 'Hiat is, it is equivalent to 

((lambda (var/ vflr-2 ...) 

form-1 form-2 . . . ) 
val-l val-2 , . . ) 

but displays the values in close proximity to the variables. 

Note tliat similar to do, a declaration is allowed as the first form in a let body. 

lit* Special Form 

let* has a syntax identical to that of let, but binds the variables in sequence rather than 
in parallel. Ihus, 

(let* ((a (foo)) (b (bar a))) 

(computaie a b)) 

is like 
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((lambda (a) 

((lambda (b) 

(computata a b)) 
(bar a))) 

(foo)) 


pat tv Special Form 

pa«tq is similar to aetq. In the multi- variable cue however, the variables are set "in 
parallel” rather than sequentually; first all the forms are evaluated, and then the symbols 
are set to t"ie resulting values. For example: 

(satq a 1) 

(aatq b 2) 

(psatq abba) 
a ■> 2 
b ■> I 


8,5 Flow of Control 
8.5.1 Conditionalii 

if predicate-form then- form [else- form] Special Form 

if is a convenient abbreviation for a simple cond which docs a binary branch, predicate- 
form is evaluated, and if the result is non-nil, then then-form is evaluated and that result 
returned, otherwise etse-form is evaluated and that result returned. If no else-form is 
specified and predicate-form evaluates to nil, then nil is returned, if can (and usually is) 
defined as a macro such that 

( if pred then else) 

(cond (pred then) (t else)) 

and 


( if pred then) 

■■> (cond (pred then) (t nil)) 
or 

■■> (and pred then) 

If there are more than three subforms, if assumes that more than one otherwise form was 
intended; liicy will be treated as an implicit progn. For example, 

(if p c el e2 e3) 

**> (cond (pc) (t e! e2 e3)) 

Iherc is dis^igrccmcnt as to whether tliis constitutes good programming style, so it is 
possible Uiat tliis last variant may be disallowed. 
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8.5.2 Selection 

ttitctq key- form clauses... Special Form 

seiectq is a conditional which chooses one of its clauses to execute by comparing the 
value of a form against various constants. Its form is as follows: 

(seiectq key-form 

( lest comequent-forms... ) 

(test consequent-formt..) 

...) 

The first thing seiectq docs is to evaluate keyfonn', call the resulting value key. Then 
seiectq considers ciich of the clauses in turn, if key matches the clauses test, the 
consequents of >'his clause arc evaluated, and seiectq returns the value of the last 
consequenL if there are no matches, seiectq returns nil. 

A test may be any of 

a symbol or integer The symbol or integer is compared with key. Symbols are 
compared using eq; integers arc compared on the same basis that 
equal uses— equal types and equal values. Note that t and 
otherwise arc exceptions here. 

a list llic list should contain only symbols and integers, which are 

compared as above. 

tor otherwise 'Hte symbols t and ctherwlse are special keywords which match 
anything. Either of these may thus Ih: used to signify a "default" 
clause, which to be useful, should be the last clause of the seiectq. 

Examples: 

(defun count-them (n) 

(seiectq n 
(0 ’none) 

(1 ’one) 

(2 ’two) 

((3 4) ’a-few) 

(t *(nany))) 

(count- them 2) ■> two 

(count-them 3) ■> a-few 

(count-them 7) -> many 

(seiectq ‘one 

(1 integer-one) 

(one ’symbol-one) 

(t ’ something-else) ) 

=> symbol -one 

If the keys being tested against and the value of keyfonn arc all of the same type, caseq 
/ should be used, as it may produce more efTiciciu code depending on the impicmentiition. 

Ihis is true in Pl)l*-10 Maclisp, which has no primitive predicate that implements the 
type of comparison that solectq uses, In Usp Machine l.isp and Multics Maclisp there 
should be no dill'crencc unless bignums are used. Presently, bignums do not work 
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anyway, but this is expected to be fixed. 

CM«q key-fimn vlauses,,. Special Fonn 

caseq is tlic siime as seloctq except that it requires all of tlic keys being compared to be 
of the same type. It is also an error for the value of key-form to be of a dilferent type 
tlian the keys in the clauses. 

Currently, in all but the PDF- 10 implementation, caseq is implemented in tenns of 
selectq so does not provide tliis consistency checking, any qualifications given for selectq 
apply to caseq. 

In PDP-IO Miiclisp, caseq does not accept the otherwise keyword; it is neccssiiry for t 
to be used, It also docs not accept bignums. 


8.5.3 Iteration 

dot 1st Special Form 

dolist is like a cross between mape and do, 

(dolt si (var list) body,,.) 

evaluates the fonns of body for ejtch element of list, with var bound to the successive 
elements, btnly is treated as a prog or do body, so it may contain prog tags, and calls 
to return, which will return from the dolist. 

do t 1ms s Special Form 

dotirr.es perfonns integer stepping, and is otherwise similar to dolist. 

(dottmes (var count) body...) 

evaluates My count times; var takes on values starting with zero, and stops before 
reaching count. For example, 

(liottmas (1 (// m n)) (frob t)) 

is equivalent to 

(do ((1 0 (1+ 1)) 

( count ( // m n) ) ) 

((not (< 1 count))) 

( f rob t ) ) 

except that tlic name count is not used. 

dotimes is similar to dolist in that the body is treated as if it were a prog or do body. 

loop Macro 

dolist and dotimes are convenient foi simple cases, where the extra syntax necessitated by 
mape or do is an annoyance. For complicated cases, the loop macro mty be desirable, 
It provides for the stcpiiing of multiple variables, either in sei|uence or in parallel, and 
methods lor peiforming various sorts of itceumul.ilions, such as colleclinst a list, summing, 
ami couniing: imne than one such accumulativtn to he performed, .md they need not be 
.iccumulaied "in sync" with the iteration, hor example, 
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(loop for X in I as y - (f x) collact (cons x y)) 
produces a result like 

(do ((•list* 1 (edr •list*)) (x) (y) (•result*)) 

((null *list*) (nrovarse *result*)) 

(setq X (car *list*)) 

(setq y (f x)) 

(setq •result* (cons (cons x y) •result*))) 

docs, loop is extremely complicated so is not documented here; full documentation may 
be found in MIT Laboratory for Computer Science I'echnical Memo 169 (January 1981). 

8.5.4 Noii’Local Exits 

*catch lag form Special Form 

llic *catch special form is used with *throw to perform non-local exits, tag is evaluated, 
and then form is evaluated. If during the evaluation of form a ('throw tag value) is 
done, then the 'catch returns vdue, 

*throw lag value 

Evaluation of ('throw tag value) causes a pending 'catch of lag to return value. 

'catch and 'throw arc slightly more general versions of the standard Maclisp catch and 
throw special forms, llicy arc more general in that the tags given to them are evaluated, and 
thus need not be written into the code, but can be passed in. Additionally, the difTcrence in 
argument ordering can make for more readable code, viz 

(•catch 'exit 
moby>-big-hairy-compuation- 
ihai- is-conlinued-over- 
many-lines) 

Lisp Machine Lisp, PDP-10 Maclisp, and NIL. support 'catch and 'throw as the basic catching 
and throwing primitives; catch and throw are implemented as macros in terms of them. Multics 
Maclisp implements 'catch and 'throw as macros in terms of the existing catch and throw 
special forms; thus it is impossible for 'catch and 'throw on Multics to accept anything but a 
quoted atom for the tag. 

It is advisiiblc for 'catch and 'throw to be used in preference to catch and throw; at some 
future time it is anticipated diat catch and throw will be changed to be equivalent to 'catch and 
'throw. Ihe names 'catch and 'throw arc expected to remain valid indefinitely. 

unwind-protect form cleanup-forms.., SpedalForm 

unwind -protect evaluates fonn and returns that result as its value, When control returns 
from the unwind -protect for any reason, whether it be a normal return, or a non-l(Kal 
exit causes by a 'throw or an error, the elemup-foms will be evaluated, unwind -protect 
can thus he used for "binding" something which is not really bindabic as a variable, or 
for pcrfoiining .some necessary cleanup action, such as closing a file. 

Example: 
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(unwlnd-protect 

(progn ( turn-on-Mater-faucet) 

( compute-under -running- water ) ) 
( tur n -of f- water- faucet ) ) 


8.6 Miscellaneous 

progl firsi forms.., Special Form 

progi is similar to prog2, only without the first argument. All of the argument to progi 
are evaluated just as they would be for progn, however, the value returned by progi will 
be die value of the first form rather than the last. For example: 

(rplaca x (progi (edr x) (rplacd x (car x)))) 
can be used to exchange the car and the edr of a cons. 

lexpr-funcall function Arest args 

lexpr-luncall is a cross bewecn funcall and apply, (leixpr-funcall function arg-l arg-2 ... 
arg-n list) calls die function function on arg-l through arg-n followed by the elements of 
list, for example 

(lexpr-funcall 'list 'a 'b ’(c d)) *> (a b c d) 

(lexpr-funcall 'plus 3 4 ’(2 1 0)) »> 12 

Note diat two argument lexpr-funcall Is the same as apply, and that lexpr-funcall with 
a list argument of nil is essentially funcall. 

without- Interrupts forms... Special Fortri 

lliis provides a convenient way of executing some code uninterruptibly. fonns arc 
evaliiatcd as with progn and the value of the last form is returned. It is guaranteed diat 
the evaluation will be performed as an atomic operation. 

ferror condition- name format-string &rc$t format-args 

ferror provides a mechanism for signalling errors using format (page 47) to generate the 
error message, condition- name is used to specify die type of condition which is to be 
signaled; no mechanism for diis exists in Maclisp, However, condition- name may be nil, 
in which case an imcorrcctablc error (x:curs— nil is therefore die only value of condition- 
mne guaranteed to work everywhere. 

Example: 

(ferror nil ”%%% Compiler error call ~S %%%" 

(get 'compiler 'maintalner ) ) 
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9. Defstruct 

9.1 Introduction 

The Features of defstruct differ slightly from one Lisp implementation to another. However, 
defstruct makes it fairly easy to write compatible code if the user doesn't try to exercise any of 
the more esoteric features of his particular Lisp implementation. The differences will be pointed 
out as they occur. 

One difference that we must deal with immediately is the question of packages, defstruct 
makes use of a large number of keywords, and on the Lisp Machine those keywords are all 
interned on the keyword package. However, for the purposes of compatibility, the Lisp Machine 
defstruct will allow the keywords to appear in any package. The Lisp Machine programmer is 
discouraged from writing keywords without colons, unless the code is to be transported to another 
Lisp implementation. Classes of symbols that defstruct treats as keywords will be noted as they 
occur. 

Other package related issues will be dealt with later. 

9.2 A Simple Example 

defstruct Macro 

defstruct is a macro defining macro. The best way to explain how it works is to show a 
sample call to defstruct. and then to show what macros arc defined and what each of 
them does. 

Sample call to defstruct: 

(defstruct (elephant (type list)) 
color 
(size 17.) 

(name (gensym))) 

This form expands into a whole rat's nest of stuff, but the effect is to define five macros: color, 
size, name, make -elephant and alter -elephant. Note tliat there were no symbols make- 
elephant or alter-elephant in tlic original form, they were created by defstruct. The definitions 
of color, size and name arc easy, they expand as follows: 

(color x) =*> (car x) 

(size X) »»> (cadr x) 

(name x) =*> (caddr x) 


You can sec tliat defstruct has decided to implement an elephant as a list of three things; its 
color, its si/.c and its name. The expansion of make-elephant is somewhat harder to explain, 
let's look at a few cases: 
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(make-elephant) ■■> (list nil 17. (gensym)) 

(make-elephant color *p1nk) ■» (list 'pink 17, (gensym)) 

(make-elephant name 'fred size 100) ■■> (list nil 100 *fred) 

As you can sec, make -elephant takes a "setq-style" list of part names and Forms, and 
expands into a call to list that constructs such an elephant. Note that the unspecified parts get 
defaulted to pieces of code specified in the original call to defstruct, Note also that the order of 
the setq-style arguments is ignored in constructing the call to list. (In the example, 100 is 
evaluated before 'fred even though 'fred came first in the make -elephant form.) Care should 
thus be taken in using code with side effects within the scope of a make -elephant. Finally, take 
note of the fact that the (gensym) is evaluated every lime a new elephant is created (unless you 
override it). 

live explanation of what alter -elephant docs is delayed until section 9.4.3, page 31. 

So now you know how to construct a new elephant and how to examine the parts of an 
elephant, but how do you change the parts of an already existing elephant? llie answer is to use 
the setf macro (chapter 7, page IS). 

(seif (name x) 'bill) »■>> (rplaca (eddr x) 'bill) 

which is what you want. 

And that is just about all there is to defstruct; you now know enough to use it in your code, 
but if you want to know about all its interesting features, then read on. 

9.3 Syntax of defstruct 

The general form of a defstruct form is: 

(defstruct {name oplion-l option-2 ... opiion-n) 
slot- description- 1 
slot-description-2 

slot-descriplion-m) . 


name must be a symbol, it is used in constructing names (such as "make-elephant") and it is 
given a defstruct -description property of a structure that describes the structure completely. 

F.ach option-i is cither the atomic name of an option, or a list of tlic form {option-name arg . 
rest). Some options have defaults for arg\ some will complain if they arc present without an 
argument; some options complain if they arc present with an argument. The inteipretation of rest 
is up to tlie option in question, but usually it is expected to be nil. 

lu'tch shi-description-j is either the atomic name of a slot in tlic structure, or a list of the 
form {slot- name mil-code), or a list of byte field specifications, inil-code is used by constructor 
macros (such as make- elephant) to initialize slots not specified in the call to die constructor. If 
the iitil-anic is not specified, then the slot is initiali/ed to whatever is most convenient. (In tlic 
elephant example, since the .structure was a list, nil was used. If the structure had been a 
(ixnuin array, such slots would be filled with zeros.) 
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A byte field specification looks like: {field-name ppss) or {field-name ppss inli-code). 5 that 
since a byte field specification is always a list, a list of byte field spcxifications can never be 
confused wiU) the other cases of a slot description, 'ntc byte field feature of defstruct is 
explained in detail in section 9.5, page 38. 

9.4 Options to defstruct 

Ihc following sections document each of the options defstruct undentands in detail. 

On the Lisp Machine, all these defstruct options are interned on the keyword package. 

9.4.1 type 

Ihc type option specifies what kind of lisp object defstruct is going to use to implement your 
structure, and how that implementation is going to be carried out, 'Ihc type option is illegal 
without an argument. If the type option is not specified, then defstruct will choose an 
appropriate default (hunks on PDP-lOs, arrays on Lisp Machines and lists on Multics). It is 
possible for tlic user to teach defstruct new ways to implement structures, the interested reader is 
referred to section 9.8, page 42, fur more infomiation. Many useful types have already been 
defined for the user. A Uiblc of tliese "built in” types follows; (On the Usp Machine all 
defstruct types arc interned on tlic keyword packiige.) 

list All implementations 

Uses a list. 'Ihis is the default on Multics. 

named - list All implementations 

Like list, except the car of each instance of this structure will be the name 

symbol of the structure. 'Ihis is the only "named" structure type defined on 
Multics. (Sec Utc named option documented in section 9.4.7, page 35.) 

tree All implementations 

Creates a binary tree out of conscs with the slots as leaves. 'Ihc theory is to 
reduce car edring to a minimum. Ihc include option (sc'ction 9.4.6, page 33) does 
not work with stnicturcs of this type. 

list* All implementations 

Similar to list, but tlic last slot in the sUucturc will be phiccd in the edr of the 
final cons of tlic list. Some people call objects of this type "dotted lists". Ihe 
include option (section 9.4,6, page 33) docs not work with stnicturcs of this type. 

array All implementations 

Uses an array object (not a symbol with an array property), Ihis is the default on 

Lisp Machines, i.isp Machine users may want to see the make-array option 
documented in section 9,4.8, page 35. 
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fixnum- array 
flonum- array 
un-gc -array 

hunk 

named -hunk 
sfa 

named -array 

array -leader 
named -array 

fixnum 


All implementations 

Like array, except it uses a fixnum array and thus your structure can only contain 
fixnuins. On Lisp Machines defstruct uses an art -32b type array for this type. 

All implemeAtations 

Analogous to fixnum-array, On Lisp Machines defstruct uses an art-float type 
array for this type. 

PDP-lOonly 

Uses a nil type array instead of a t type. Note that this type does not exist on 
Lisp Machines or Multics, because un-garbage-collected arrays do not work in 
those implementations. 


Uses a hunk. ITtis is the default on PDF- 10s. 


POP- 10 only 


PDP- 10 only 

Like hunk, except the car of each instance of this structure will be the name 
symbol of the structure. This tan be used with Uie (status usrhunk) feature of 
PDP- 10 Maclisp to give the user Lisp Machine-like named structures. (See the 
named option documented in section 9.4.7, page 35.) 


PDP- 10 only 

Uses an SFA. ITie constructor macros for this type accept the keywords sfa- 
function and sfa-name. llieir arguments (evaluated, of course) are used, 
respectively, as the function and the printed representation of the SFA. See also 
tire sfa-function (section 9.4.9, page 35) and sfa-name (section 9.4.10, page 36) 
options. 

Lisp Machine only 

Uses an array wiOi the named structure bit set and stores the name symbol of the 
structure in the first element, (See the make -array option documented in section 
9.4.8, page 35.) 

Lisp Machine only 

Uses an array with a leader. (See the make- array option documented in section 
9.4.8, page 35.) 

leader Lisp Machine only 

Uses an array with a leader, sets the named structure bit, and stores the name 
symbol in clement 1 of the leader. (See the make- array option documented in 
section 9.4.8, page 35.) 


All implementations 

'ITiis type allows one to use tlic byte field feature of defstruct to deal symbolically 
with fixnums that aren’t actually stored in any structure at all. Essentially, a 
structure of type fixnum has exactly one slot. 1'his allows tlic operation of 
retrieving the contents of th;it slot to be optimized away inu» the identity 
operation. See section 9.5, page 38 for more information about byio fields. 
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external Muhicsonly 

Uses an array of type external (only Multks Lisp has these). Constructor macros 
for structures of this kind take the external -ptr keyword to tell them where the 
array is to be allocated. (See section 9.4.2, page 30, for an explanation of 
constructor macro keywords.) See also the external *-ptr option described in section 
9.4.11, page 36. 

9.4.2 constructor 

The constructor option specifies the name to be given to the constructor macro. Without an 
argument, or if the option is not present, the name defaults to the concatenation of "make-" with 
the name of the structure. If the option is given with an argument of nil, then no constructor is 
defined. Otherwise the argument is the name of the constructor to define. Normally the syntax 
of the constructor defstruct defines is: 

( constructor-name 
keyword- 1 code- 1 
keyword-2 code-2 
• • • 

keyword- n code-n) 

Each keyword-! must be the name of a slot in the structure (not necessarily the name of an 
accessor macro; sec the cone -name option, section 9.4.5, page 33), or one of the special 
kcywtrrds allowed for the particular type of structure being constructed, For each keyword that is 
the name of a slot, tlic constructor expands into code to make an instance of the structure using 
code-i to initialize slot keyword-i. Unspecified slots default to the forms given in the original 
defstruct form, or, if none was given there, to some convenient value such as nil or 0. 

For keywords that arc not names of slots, the use of the corresponding code varies. Usually 
it controls some aspect of the instance being constructed that is not otherwise constrained. See, 
for example, the make-array option (section 9.4.8, page 35), the sfa-function option (section 
9.4.9, page 35, or the external-ptr option (section 9.4.11, page 36). 

On the Lisp Machine all such constructor macro keywords (those that arc not the names of 
slots) arc interned on the keyword package. 

If the constructor option is given as (constructor name arglist), then instead of making a 
keyword driven constmetor, defstruct defines a "function style" constructor. Iltc arglist is used 
to describe what tlic arguments to the constructor will be. In the simplest case something like 
(constructor make-foo (a b c)) defines make-foo to be a three argument constructor nuicro 
wliosc arguments arc used to tniiiati/e the sluts named a, b and c. 

In addition, the keywords fioptional, &rest and &aux are recognized in tlie argument list, 
nicy work in the way you might expect, but there arc a few fine points worthy of explanation: 

(constructor make-foo 

(a Sioptlonal b (c ’sea) &rest d Sroux e (f ’eff))) 

This (Icfincs make-foo to be a constructor of one or more argimionts, I'hc first argument is used 
to initiali/e the a slot. The ,sec<»nd argument is used to initialize the b slot. If there isn’t aiiy 
.second argumcni, then the dol'auli value given in the body of the defstruct (if given) is used 
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instead, lltc third argument is used to initialise the c slot, If there isn’t any tltird argument, 
tlicn the symbol sea is used instead, 'fhe arguments from the fourth one on are collected into a 
list and used to initialise the ti slot. If there arc three or less arguments, then nil is placed in the 
d slot. Ihc e slot is noi Mlializat It’s value will be something convenient like nil or 0. And 
finally the f slot is initialised to contain the symbol off. 

The b and e cases were careftilly chosen to allow the user to specify all possible behaviors. 
Note that the &aux "variables" can be used to completely override the default initialisations given 
in die body. 

Since there is so much freedom in defining constructors this way, it would be cruel to only 
allow the constructor option to be given once. So, by special dispensation, you are allowed to 
give the constructor option more than once, so that you can define several different constructors, 
each with a different syntax. 

Note that even these "function style" constructors do not guarantee that their arguments will 
be evaluated in the order that you wrote them. 


9.4.3 alterant 

'Ilie alterant option defines a macro that can be used to change the value of several slots in a 
structure together. Without an argument, or if the option is not present, the name of tlie alterant 
macro defaults to the concatenation of "alter-" with the name of the structure. If the option is 
given with an argument of nil, then no alterant is defined. Otherwise die argument is the name 
of die alterant to define, I’he syntax of the alterant macro defstruct defines is: 

( alterant’ name code 
slot’ name- 1 code- 1 
slot’name’2 code-2 

slot-name-n code-n) 

code should evaluate to an instance of the structure, each code-i is evaluated and the result is 
made to be the value of slot sht-name-i of that structure. The slots arc all altered in parallel 
after all code has been evaluated. (Thus you can use an alterant macro to exchange the contents 
to two slots.) 

Example; 

(defstruct (lisp-hacker (type list) 

conc-nama 

default-pointer 

alterant) 

(favorite-macro-packaga nil) 

(unhappy? t) 

( number-of-f riends 0)) 

(setq lisp-hacker (make-lisp-hacker)) 

Now' wc can perform a transformation: 
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(altar-Hsp'hackar llap-hackar 

favor Ua-macro-peckaga 'daf struck 
nu«bar-of-fr lands 23. 
unhappy? nil) 

-•» ((lambda (GOOOO) 

((lambda (60011 60010) 

(satf (car 60009) 'dafstruct) 

(satf (caddr G0009) GOOll) 

(satr (cadr GOOOO) 60010)) 

23. 

oH)) 

llsp-hackar) 

Although it appears from this example that your forms will be evaluated in the order in 
which you wrote them, this is not guaranteed. 

Alterant macros arc particularly good at simult/incously modifying several byte fields that are 
allocated from the same word, 'fhey produce better code than you can by simply writing 
consecutive setfs. 'rhey also produce better code when modifying several slots of a structure that 
uses the but -first option (section 9,4. IS, page 37). 

9.4.4 dcfauU'pointer 

Normally tlic Jiccessors arc defined to be macros of exactly one argument, ffhey check!) But 
if Uic default -pointer option is present then they will accept zero or one argument. When used 
with one argument, tficy behave as before, but given no arguments, they expand as if they had 
been called on the argument to the default -pointer option. An example is probably called for; 

(def struct (room (type tree) 

( default- poll) tar •«current-room*«) ) 

(room-name ’y2) 

(room-contents-l 1st nil)) 

Now the accessors expaod as follows; 

(room-name x) •■> (car x) 

(room-name) ■•> (car ••current-room**) 

If no argument is given to the default- pointer option, then the name of the structure is used 
as the "default pointer", default -pointer is most often used in this fashion. 
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9.45 conc'iumie 

Frequently all the accessor macros of a structure will want to have names that begin the same 
way; usually with the name of the structure followed by a dash. Ilie conc'-name option allows 
the user to specify tliis prefix, its argument should be a symbol whose print name will be 
concatenated onto the front of the slot names when forming »hc accessor macro names. If the 
argument is not given, then the name of the structure followed by a dash is used. If the ccnc- 
name option is not present, then no prefix is used. An example illustrates a coinmcn use of the 
conc-name option along with the default -pointer option; 

(defstruct (locetlon default-pointer 

conc-name) 

{n 0 ) 

(y 0) 

(* 0 )) 

Now if you say 

(setq location (make-location x 1 y 34 z 6)) 
it will be the case that 
( locatlon-y ) 

will return 34. Note well that the name of the slot ("y") and the name of the accessor macro for 
that slot ("location-y") arc different. 

9.4.6 Include 

'llie include option inserts tlie definition of its argument at the head of the new structure's 
definition, in otlicr words, the first slots of the new structure arc equivalent to (i.c, have the 
same names as, have the same inits as, etc.) the slots of the argument to the include option. 
The argument to the include option must be tlic name of a previously defined structure of the 
same type as the new one. if no type is specified in the new structure, then it is defaulted to 
that of the included one. It is an error for tlic include option to be present without an 
argument, Note tliat Include docs not work on certain types of structures (c.g. structures of type 
tree or list*). Note also that the conc-name, default -pointer, but -first and callable - 
accessors options only apply to the accessors defined in the current defstruct; no new accessors 
arc defined for the included slots. 
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An example: 

(defstruct (person (type Ust) 

conc-name) 

name 

age 

tex) 

(defstruct (spaceman (Include person) 

default-pointer) 

helmet-sixe 

(favorite-beverage 'tang)) 

Now we can make a spaceman like this: 

(setq spaceman (make-spaceman name 'buzx 

age 46. 
tex t 

helmet-size 17.6)) 

I'o find out interesting tilings about spacemen: 

(helmet-size) »■> (cadddr spaceman) 

(person-name spaceman) »■> (car spaceman) 

(favorite-beverage x) ■■> (car (eddddr x)) 

As you can see the accessors defined for the person structure have names that start with 
"person-" and tlicy only take one argument. The names of the accessors for the last two slots of 
tlic spaceman structure arc the same as the slot names, but tlicy allow their argument to be 
omitted. Hie accessors for the first three slots of the spaceman stnicture arc the same as the 
accessors for the person structure. 

Often, when one structure includes another, the default initial values supplied by the included 
structure will be undesirable. 'Iliese default .initial values can be modified at the time of inclusion 
by giving the include option as: 

(include name new Ml- 1 ... new-inii-n) 

Each ne^inii-i is either the name of an included slot or of the form {includeii- slot- name neye-init). 
If it is just a slot name, tlien in tlie new structure (the one doing the including) that slot will 
have no initial value, If a new initial value is given, then that code replaces the old initial value 
code for tliat slot in Uie new structure, 'ilie included structure is unmodified. 
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9.4.7 named 

I’his option tells defstruct that you desire your si.nicture to be » "named structure". On 
PDF- 10s this means you want your structure implemented with a named -hunk or named list, 
On a Eisp Machine this indicates that you desire either a named -array or a named -array - 
leader or a named -list. On Multics this indicates that you desire a named -list, defstruct bases 
its decision as to what named type to use on whatever value you did or didn’t gi\c to tlic type 
option. 

It is an error to use this option with an argument. 

9.4.8 niake*array 

Available only on l-isp Machines, this option allows the user to control tltosc aspects of the 
array used to implement tlic structure Uiat are not otherwise constrained by defstruct (such as ihc 
area it is to be allocated in). 

The argument to the make-array option should be a list of alternating keyword symbols to 
tlte l.isp Machine make-array function (sec the Usp Machine manual), and form., whose values 
arc to be Uic arguments to ilrose keywords. For ex.'jmplc, (make- array ( type art 4b)) would 
rcquc.st that Uic type of iJic array he art-4b, Note that die keyword symbols arc noi evaluated. 

Constructor macros for structures implemented as arrays all allow the keyword make-array to 
be .supplied, Us argument is of the same form as Uic make- array option, and aUributc.s specified 
Uierc (in the constructor form) will override those given in the defstruct form. 

Since it is sornctimc.s necessary to be able to specify Uic dimensions of the array dial 
defstruct is going to construct (for .stmetures of type array-leader for example) the make array 
option or constiuetor keyword accepts die additional keywords Uength and :dimensiori (they mean 
die same diing), 'ITic argument lo this pscudt) make-array keyword will be supplied as the first 
argutncni to die make-array function when the constructor is expanded, 

defstruct ehoo.scs appropriate defaults for those atidbutcs not specified In the defstruct form 
or in die constructor form, and defstruct overrides any' specified attributes dial it has to. 


9.4.9 sfa-fuiiction 

Available only on Pl)l*-10s, this option allows the user to specify the function that will be 
used in structures of type sfa, Its argument should be a piece of code ih;it evaluates to the 
desired function, Constructor macros for this type of structure will utke sfa -function as a 
keyword whose argument is also the code to evaluate to gel the function, ovcrridi ig any supplied 
in the original defstruct form, 

If sfa-function is not present anywhere, then the constructor v/ill use die name-symbol of the 
.structure as the function. 
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9.4.10 sfa-name 

Available only on PDF- 10s, this option allows the user to specify the object that will be used 
in the printed representation of structurts of type sfa. its argument should be a piece of code 
that evaluates to that object. Constructor macros for this type of structure will take sfa-name as 
a keyword whose argument is also the code to evaluate to get tlic object to use, overriding any 
supplied in the original defstruct form. 

If sfa-name is not present anywhere, then the constructor will use the name-symbol of the 
structure as the function. 


9.4.11 extcrnal'ptr 

Available only on MuUics, this option is used with structures of type external. Its argument 
should be a piece of code that evaluates to a fixnum "packed pointer" pointing to the first word 
of tlic external array tire defstruct is to constiuct. Constructor macros for this type of structure 
will take external -ptr as a keyword whose argument overrides any supplied in the original 
defstruct form. 

If external -ptr is not present anywhere, then the constructor signals an error when it 
expands. 

9.4.12 size-symbol 

'Hie size -symbol option allows a user to specify a symbol whose value will be the "size" of 
the slnicturc. 1hc exact meaning of this varies, but in general this number is the one you would 
need to know if you were going to allocate one of these structures yourself. Ihc symbol will 
have this value both at compile time and at run time. If this option is present without an 
argument, then the name of tlic structure is concatenated with "-size" to produce the symbol, 


9.4.13 size-macro 

Similar to size-symbol. A macro of no arguments is defined that expands into the size of 
the structure. 1’hc name of this macro defaults as witli size-symbol. 

9.4.14 initial-offset 

Hiis option allows you to tell defstruct to skip over a certain number of slots before it starts 
allocating tlic slots described in the body. This option requires an argument, which must be a 
fixnum, which is tlic number of slots you want defstruct to skip. 'I'o make use of this option 
requires that you have some familiarity with how defstruct is implementing you structure, 
otherwise you will be unable to make use of the slots tliiit defstruct has left unused. 
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9.4.15 but'flrst 

This option is best explained by example: 

(defstruct (head (type list) 

(default-pointer person) 

(but-first person-head)) 

nose 

mouth 

eyes) 

So now the accessors expand like this: 

(nose x) “»> (car (person-head x)) 

(nose) “*> (car (person-head person)) 

ITic theory is tliat but-first’s argument will likely be an accessor from some other structure, 
and it is never expected that tliis structure will be found outside of that slot of tliat other 
structure, (In tlie example I had in mind that there was a person structure which had a slot 
accessed by person -head,) It Is an error for the but-first option to be used without an 
argument. 

9.4.16 callable*acccssors 

This option controls whether tlie accessors defined by defstruct will work as "functional 
arguments", (As tlie first argument to mapear, for example.) On tlie Usp Machine accessors arc 
callable by default, but on FDP-lOs it is expensive to make this work, so they arc only callable if. 
you ask for it, (Currently on Multics the feature doesn’t work at all,,,) The argument to this 
option is nil to indicate that the feature should be turned off, and t to turn tlie feature on. If 
the option is present with no argument, tlicn the feature is turned on. 


9.4.17 cval-when 

Normally tlie macros defined by defstruct arc defined at eval-timo, compilc-time and at load- 
time. 'fhis option allows the user to control tliis behavior, (eval-when (eval compile)), for 
example, will cause die macros to be defined only when the code is running interpreted and 
inside the compiler, no trace of defstruct will be found when running compiled code. 

Using the eval-when option is preferable to wrapping an eval-when around a defstruct 
fonn, since nested evhl-whens can interact in unexpected ways. 
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9.4.18 property 

For each structure defined by defstruct, a property list is maintained for the recording of 
arbitrary properties about that structure. 

'Fhe property option can be used to give a defstruct an arbitrary property, (property 
properl}'- name value) gives the defstruct a property-name property of value, Neither argument is 
evaluated. To access the property list, the user will have to look inside the defstruct-descriptlon 
structure himself, he is referred to section 9.7, page 41, for more information. 


9.4.19 A Type Used As An Option 

In addition to the options listed above, any currently defined type (a legal argument to the 
type option) can be used as a option. This is mostly for compatibility with the old Eisp Machine 
defstruct. It allows you to say just lype when you should be saying (type type). Use of this 
feature in new code is discouraged. It is an error to give an argument to a type used as an 
option in tliis manner, 

9.4.20 Other Options 

E’inally, if an option isn’t found among tliosc listed above, defstruct checks tire property list 
of die name of the option to see if it has a non-null defstruct -option property. If is does have 
such a property, tlicn if the option was of the form (option- name value), it is treated just like 
(property option-name value). Ihat is, the defstruct is given an option-name property of value. 
It is an error to use such an option witlrout a value. 

I’his provides a primitive way for the user to define his own options to defstruct. Several of 
the options listed above arc actually implemented using this mechanism. 


9.5 Byte Fields 

On Multics, the byte field feature will not work unless the user has arranged to define the 
functions Idb and dpb (section 8.1.2, page 18). ITiey arc not yet present in the default 
environment, but they arc available as part of tlic extension library (.section 11.2, page 59). 

’I’lie byte field feature of defstruct allows tlie user to specify tliat several slots of his structure 
are bytes in a fixed point number stored in one element of the structure. For example, suppose 
we had the following structure: 

(defstruct (phone-book-entry (typo list)) 
name 
address 

(area-code 617 . ) 

exchange 

line-number) 

This SNill \sork just fine, lixeept you notice that an area-code and an exchange arc both always 
Ic.ss th.m 1000,, and so both can easily fit in 10. bits, and tltc line-number is always Ic.ss ihan 
100(H), and can ‘thus fit in 14. bits, Tluis you can pack all three parts of a phone number in 34. 
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bite. If you have a lisp with 36. bit fixnums, then you should be able to put the entire phone 
number in one fixnum in a structure, defstruct allows you to do tliis us follows; 

(defstruci (phone-book-antry (type list)) 

name 

address 

((area-coda 3012 617.) 

(exchange 1612) 

(line-number 0016))) 

Ihc magic numbers 3012, 1612 and 0016 are byte specifiers suitable for use with the functions 
Idb and dpb (page 18). 11iings will expand as follows: 

(area-code pbe) >.=> (Idb 3012 (caddr pbe)) 

(exchange pbe) =“> (Idb 1612 (caddr pbe)) 

(make -phone -book -entry 

name ’ | Fred Derf | 
address ’ |269 Octal St. | 
exchange ex 
line-number 7788.) 

==> (list 'iFred Derf| '1269 Octal St. | (dpb ex 1612 115100017154)) 

(alter-phone-book-entry pbe 

exchange ex 
line-number In) 


-=> 


((lambda (G0003) 

(setf (caddr G0003) 

(dpb ex 1612 (dpb In 0016 (caddr G0003))))) 

pbe) 


defstruct tries to be ma.ximally clever about constructing and altering structures with byte 
fields. 

1lic byte specifiers arc actually pieces of code tltat are expected to evaluate to byte specifiers, 
but defstruct will try and understand fixnums if you supply them. (In tlie make- phone-book 
example, defstruct was able to make use of its knowledge of tlie line-number and area-code 
byte specifiers to assemble tlie constant number 115100017154 and produce code to just deposit 
in the exchange.) 

A nil in tlie place of tlie byte specifier code means to define an accessor for the entire word. 
So we could say: 
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(defstruct (phone-book-entry (type list)) 
name 
address 

((phone-number nil) 

( area-code 3012 617 . ) 

(exchange 1612) 

(line-number 0016))) 

to enable us to do things tike: 

(setf (phone-number pbel) (phone-number pbe2)) 
to cause two entries to have the same phone numbers. 

We could also have said just: ((phone -number) ...) in that last defstruct, but the feature of 
nil byte specitiers allows you to supply initial values for the entire slot by saying: ((name nil mil) 
...). 


Constructor macros initialize words divided into byte Acids as if they were deposited in the 
following order: 

1) initializations for the entire word given in the defstruct form. 

2) Inl i .tions for the byte fields given in the defstruct form. 

3) Initializations for the entire word given in the constructor macro form. 

4) Initializations for the byte fields given in the constructor macro form. 

Alterant macros operate in a similar manner, ITiat is, as if the entire word was modified first, 
and tlicn the byte fields were deposited. Results will be unpredictable in constructing and altering 
if byte fields that overlap are given, 

9.6 About Autoloading 

'Phis section only applies to PDF- 10 and Multics Lisp. 

If you look at the property lists of the macros defined by defstruct, you will find that they 
are all have macro properties of one of four functions: defstruct -expand -ref -macro, defstruct- 
expand-cons-macro, defstruct -expand -alter -macro and defstruct-expand-size-macro. 

These functions figure out how to expand the macro by examining the property list of the car of 
the form they :ue asked to expand, defstruct -expand -ref -macro, for example, looks for a 
defstruct-slot, property, which should be a cons of the form (structure- name . slot-name). 

Since tlie defstruct form only expands into putprops of the desired functions (instead of 
actually constructing a full-fledged definition), loading a compiled file containing a defstruct 
merely adds a few properties to some symbols. Ilic run time environment is not needlessly 
cluttered with unwanted list structure or subr objects, If tlic u.scr thinks he may wish to asc any 
of the macros defined by dolulruct after compiling his file, he need only give tlic four expanding 
functiotis autoload properties of the name of the file containing defstruct itself. 
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For purposes of using defstruct interpreted, the two symbols defstruct and defstruct- 
define-type should be given similar autoload properties. 'Rius six symbols witlt autoload 
properties suffice to make defstruct appear loaded at all times. 

9.7 The dcfstruct*dcscription Structure 

This section discusses the internal structures used by defstruct that might be usefUl to 
programs that want to interface to defstruct nicely. The information in tliis section is also 
necessary for anyone who h thinking of defining his own structure types (section 9.8, page 42), 
IJsp Machine progr.ammcrs will find that the symbols found only in this section arc alt interned 
in the "systcms-intcrnals" package. 

Whenever the user defines a new structure using defstruct, defstruct creates an instance of 
the defstruct -description structure. This structure can be found as tlic defstruct -description 
property of the name of the stnicturc; it contains such usefiji information as the name of the 
structure, the number of slots in the structure, etc. 

7'he defstruct -description stnicturc is defined something like tliis: ('Hiis is a bowdlerized 
version of the real thing, 1 have left out a lot of tilings you don’t need to know unless you arc 
actually reading the code.) 

(defstruct ( defstruct-descriptlon 

(default-pointer description) 

( cone -name def s true t-descript ion- ) ) 

name 

size 

property-al 1st 
s1ot~a11st) 

'Fhe name slot contains the ‘symbol supplied by the user to be the name of his structure, 
something like spaceship or phone-book-entry. 

ITie size slot contains the total number of slots in an instance of this kind of structure, 'Fhis 
is not tlic same number as tliat obtained from Uic size-symbol or size-macro options to 
defstruct. A named structure, for example, usually uses up an extra location to store tlic name 
of the structure, so the size -macro option will get a number one larger than tliat stored in the 
defstruct description. 

The profierty-alist slot contains an alist with pairs of the form (property- name . property) 
containing properties placed there by the property option to defstruct or by property names used 
as opticas to defstruct (sec section 9.4,18, page 38, and section 9.4.20, page 38). 

’Hie slot-alist slot contains an alist of pairs of the Ibnn (slot-name , slot- desaipt ion). A slot- 
description is an instance of tlic defstruct-slot-description structure. 'I’hc defstruct-slot- 
description structure is defined something like tliis: (another bowdlerized defstruct) 
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(dsf struct (daf struct- slot -descript Ion 

(default -pointer slot-description) 

(cone -name daf struct- slot-descript Ion- ) ) 

number 

ppss 

Init-code 

ref-macro-name) 

'I1ic number slot contains the number of tlie location of this slot in an instance of the 
structure. Locations arc numbered sUirting with 0, and continuing up to one less than the size of 
the structure. 'Hie actual location of the slot is determined by the reference consing code 
associated with tlie type of tlie structure. Sec section 9.8, page 42. 

'Ilic ppss slot contains llie byte specifier code for tiris slot if this slot is a byte field of its 
location. If this slot is die entire location, then tire ppss slot contains nil. 

Hie init-code slot contains the initialization code supplied for this slot by the user in his 
defstruct form. If there is no initialization code for tins slot tlien tlic init-code slot contains the 
symbol %%defstruct-empty%%. 

The ref -macro -name slot contains the symbol that is defined as a macro that expands into a 
reference to tliis slot. 

9.8 Extensions to defstruct 

defstruct-def ine-type Macro 

The iriacro defstruct -define -type can be used to teach defstruct about new types it can 
use to implement structures. 


9.8.1 A Simple Example 

Let us start by examining a sample call to defstruct -define -type. 'Iliis is how tire list type 
of stmeture might have been defined; 

(def struct-def ine-type list 

(cons (initialization-fist description keyword-options) list 
(cons 'list inltlalizatlon-Hst)) 

(ref (slot-number description argument) 

(list 'nth slot-number argument))) 

I'his is the minimal example. We have provided defstruct with two pieces of code, one for 
consing up forms to construct instances of the structure, the other to cons up fonns to reference 
various elements of the stmeture. 

I'rom the example we can see that tlic constructor consing code is going to be run in an 
environment where tlie variable initialization list is botiiul to a list which is the initiali/ations to 
the slots of the struciuro arr.inuod in order, The variable description will be bound to the 
defstruct description siriiciure for the slnictnre we are consing a constructor for. (See section 
9,7. page dl.) The binriing of the variable keyvword- options will be described later, Also the 
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symbol list appears aAer the argument list, this conveys some information to defstruct about how 
the constructor consing code wants to get called. 

The reference consing code gets run with the variable slot -number bound to the number of 
the slot that is to be referenced and the variable argument bound to the code tliat appeared as 
the argument to the accessor macro, llic variable description is again bound to tlie appropriate 
instance of the defstruct -description suucture. 

Iliis simple example probably tells you enough to be able to go ahead and implement other 
structure types, but more details follow. 

9.8.2 Syntax of defstnict-deflne'type 

The syntax of dcfstruct-dcfine-type is 

(def struct-def ine-type type 
oplioft I 

opiion-n) 

where each opiion-i is eitlicr the symbolic name of an option or a list of the form (option-i , 
rest), (Actually opiion-i is the SJime as {option-i)) Different options inteipret rest in different 
ways. 

The symbol type is given a defstruct -type-description property of a stnicture tliat describes 
the type completely. 

9.8.3 Options to dclstruct'dcfine’type 

lliis section is a catalog of all the options currently known about by dejf struct -def ine-type, 

9.8.3. 1 cons 

'Fhc cons option to defstruct-define-type is how the user supplies defstruct with the 
necessary code that it needs to cons up a form that will construct an instance of a structure of 
this type. 

ITie cons option has the syntax: 

(cons {inils description keywords) kind 
body) 


body is .some code tliat should construct and return a piece of code tliat will construct, 
initialize and return an instance of a stnicture of tliis type. 

The symbol inits will be bound to the code that the constructor conscr should use to initialize 
the slots of the structure, The exact form of this aiinimoni is doicrmincd by the syi ibol kind. 
riicrc arc currently two kinds of initialization. 'I here is the list kind, where inits is .jound to a 
list of initializations, in the correei order, with nils in uninitialized .slots. And there is the alisf 
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kind, where iniis is bound to an alist with pairs of the form (shi number , inii-code). 

Hie symbol JescripiUm will be bound to the insUince of tlie defstruct -description structure 
(section 9.7, page 41) Uiat defstruct maintains for this particular structure, litis is so Utat the 
constructor conscr can find out such things as the total sire of the structure it is supposed to 
create. 

'Ilic sytnbol keywords will be bound to a alist witli pairs of the fomt {keyword , value), 
where each keyword was a keyword supplied to the constmetor niiicro that wasn’t Uic name of a 
slot, and value was tlic "code" that followed the keyword. (See section 9.8, .1.5, page 45, and 
section 9.4.2, page 30.) 

It is an error not to supply the cons option to defstruct -define -type. 

9.8..1.2 ref 

Ilic ref option to defstruct -define -type is how the user supplies defstruct with tlic necessary 
code Uiat it needs to cons up a fonn that will reference an instance of a structure of Uiis type. 

Ilic ref option has Uic syntax; 

(ref ( number description arg-l . . . arg-n) 
body) 


body is .some code Uiat should construct and return a piece of ctwlc Uiat will reference an 
instance of a stnicturc of Uiis type, 

Ihc symbol number will be bound to the location of the slot Uiat Uic is to be referenced, 
'Uiis is Uie satnc number that is found in the number slot of Uic defstruct-slot-description 
structure (section 9,7, page 41), 

'Ilic symbol description will be bound to Uic instance of the defstruct -description structure 
that defstruct maintains for Uiis particular sUucture, 

'Ilic symbols arg-i arc bound to Uie fonns supplied to Uic accessor as arguments, Normally 
there should be only one of these, llie last argument is Uic one Uiat will be defaulted by the 
default “pointer option (.section 9.4.4, page 32). defstruct will check Uiat the user has supplied 
exactly n arguments to the accessor macro before calling Uic reference consing code. 

It is an error not to supply the ref option to defstruct-define-type. 
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9.83.3 overhead 

The overhead option to defstruct-define-type is how the user declares to defstruct that the 
implementation of this particular type of structure "uses up" some number of slots kKalions in the 
object actually constructed, 'Hiis option is used by various "named" types of structures that store 
the name of the structure in one location. 

llic syntax of overhead is; 

(overhead n) 

where n is a fixnum that says how many locations of overhead this type needs. 

This number is only used by the size-macro and size-symbol options to defstruct. (Sec 
section 9,4.13, page 36, and section 9.4.12, page 36.) 


9.5.3.4 named 

The named option to defstruct-define-type controls the use of tlic named option to 
defstruct. With no argument the named option means that this type is an acceptable "named 
structure", With an argument, as in (named lype-nmw), Uic symbol lypc-mtme should be tliat 
name of some other structure type that defstruct should use if someone asks for the named 
version of tliis type. (For example, in the definition of tlie list type the named option is used 
like this: (named named-list).) 

9.8.3.5 keywords 

The keywords option to defstruct-define-type allows the user to define constructor keywords 
(section 9.4.2, page 30) for this type of structure. (For example die make-array constructor 
keyword for structures of type array on Lisp Machines.) ITic syntax is: 

(keywords keyword- ! . . . keyword-n) 

where each keyword- i is a symbol tliat the constructor conscr expects to find in the keywords alist 
(section 9.8.3. 1, page 43). 

9.5.3.6 defstruct 

1’hc defstruct option to defstruct-define-type allows the user to run some code and return 
some forms as part of tlie expansion of llic defstruct macro. 

The defstruct option has die syntax: 

(defstruct { description ) 
body) 

body is a piece of code that will he run whenever defstruct is cxpaiuling a defstruct form 
dial defines a structure of this type. The symhul dcsenpiiaii will he hound to ilie instance of the 
defstruct -doscription structure tliat defstruct iiiaimain.s for this particular struciurc. 
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'llic value returned by the defstruct option should be a list of forms to be included with 
tiiusc that the defstruct expands into. TliuSi if you only want to run some code at defstruct 
expand time, and you don't want to actually output any additional code, then you should be 
carehil to return nit from the code in this option. 
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10. Format 

f cirmat destinaiion control-siring (any-numbcr-of <irgj) 

format is used to produce formatted output, formal outputs tlic characters of control’ 
siring, except that tilde introduces a directive, 'fhe character after the tilde, 

possibly preceded by arguments and modifiers, specifics what kind of formatting is desired. 
Some directives use an clement of args to create their output, 

llie output is sent to destination . If destination is nil, a string is created which contains the 
output (sec section 10,4 on format and strings, page 57), If destination is t, tlie output is sent to 
the "default output destination", which in Maclisp is the output filespcc nil— the terminal 
(controlled by the variable ''w) and outfiles (controlled by ^r), With those exceptions, destination 
may be any legitimate output file spccincation. 

A directive consists of a tilde, optional decimal numeric parameters separated by commas, 
optional colon (";") and atsign ("@") modifiers, and a single character indicating what kind of 
directive this is, 'nic alphabetic case of Uic character is ignored. Examples of control strings: 

"«S " : 'Phis is an S directive with no parameters. 

"~3 ,4:9s" : 'Phis is an S directive with two parameters, 3 and 4, 

; and both tire colon and atsign flags. 

format includes some extremely complicated and specialized features, It is not necessary to 
understand all or even must of its features to use format elTicicntly, The beginner .should skip 
over anything in tire following documenuition tliat is not immediately useful or clear. The more 
sophisticated features arc there for the convenience of programs with complicated fomiatting 
requirements, 

Sometimes a numeric parameter is used to specify a character, for instance the padding 
character in a right- or left-justifying operation. In tins case a single quote (') followed by the 
desired character may be used as’a numeric argument. For example, you can use 

"~6, ’Od" 

to print a decimal number in five columns with leading zeros (the first two parameters to ~D arc 
the number of columns and the padding character). 

Itt place of a numeric parameter to a directive, you can put tlic letter v, which takes an 
argument from args as a parameter to tlic directive. Normally this .should be a number but it 
doesn't really have to be, 'Phis feature allows variable column-widths and tlic like, Also, you can 
use tJie character ^ in place of a parameter; it represents tlic number of arguments remaining to 
be prtKCSscd. 

It is possible to have a directive name of more than one character, The name need simply be 
enclosed in backslashes ("\"); for example, 

(format t "~\now\" (status daytime)) 

As alwiiys, case is ignored here. There is no way to quote a backslash in such ;i consiriict. No 
inulti-ch.iracier operatois come with format. 
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Note that tile charactei's and \ which are used by format are special to die default 

Multits input processor, and may need to be quoted accordingly when typed in (normally, with 


Once upon a time, various strange and wonderful interpretations were made on controlsiring 
when it was neither a string nor a symbol. Some of these arc still supported for compatibility 
with existing code (if any) which uses Uiem; new code, however, should only use a string or 
symbol for murohstmig, 

riiis document describes an implementation of format which is currently in use in Maclisp 
(botli IM)I'-10 and Multics), and is intended to be transported to Nil , It thus is oriented towards 
tile Maclisp dialect of 1 isp. fhe behaviour of format operators should be fairly consistent across 
1 isp dialects; entries cUKumented here other than format, however, exist only in the Maclisp 
impiementation at tliis time, although tlicy could be added to other format implementations 
without difficulty, 

lO.t The Operators 

Here arc the operators. 

~A arg, any I isp object, is printed without slashification (like princ). ~«A inserts spaces 
on tlic right, if nccessiiry, to inak” the column width at least n, 

is the full form of ~A, which alluws aicboratc control 
of the padding, The string is padded on tlic right with at least mmpml copies of 
ptiiklkin padding characters arc tlion inserted eolitw characters at a lime until Uic total 
width is at least mimvl. I'hc defaults arc 0 for nunvo! and minpaJ, 1 for coUnc, and 
spai'c for paih’har. The atsign modifier causes the output to be right-justified in the 
field instead of Icll-jusiified. ( Ihc same algorithm for calculating how many pad 
characters to output is used,) The colon modifier causes an arg of nil to be output as 
0 . 

~S ’I'his is identical to --A except tliat it uses prln1 instead of princ. 

~D Decimal integer output, org is printed as a decimal integer, ~u,m,oD uses a column 

width of H, padding on the left with pad-character m (default of space), using the 
chaiacter o (dorauli comma) to separate groups of Uirec digits, 'I'hcse commas arc 
only inserted if tlie : modifier is present. Additionally, if the @ modifier is present, 
iltcn the sign character will be output unconditionally: normally it is only output If 
die integer is negative. If urg is not an integer, dten it is output (using princ) right- 
justified in a field n wide, using a pad-chanteter of m, with base decimal and 
♦nopoint bound to t. 

~0 (“tctal integer output. Just like ~D. 

If prg is not 1, a lower-case "s" is printed. ("P" is for "plural",) ~:P docs tlic same 
thing, after hackiisg up an argument (like below); it prints a lower-case s if 

the /list argoment was not I, ~@P prints "y" if Uic argomem is 1, or "ics" if it is 
not. ~;@P docs the same thing, but backs up first, 

I'xamplc; 

(format nil "~D KiU~:0P" 3) => "3 Kitties" 
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-• ignores one arg, -n* ignores the next n arguments, n may be negative, 

backs up one arg; ~n;* backs up n args. 

~nG "Goes to" the «th argument, ~0G goes back to the first argument in args, 
Directives after a ~«G will take sequential arguments after tlic one gone to. Note 
that this command, and only alTcct the "local" args, if "control" is within 
something like ~(, 

~% Outputs a newline. ~n% outputs n newlines. No argument Is used, 

~4 The fresh~line operation is performed on the output stream. outputs «-1 

newlines after the fresh-line, The fresh -line operation says to do a terpri unless the 
cursor is at the start of tlie line, Ihis operation will virtually always succeed in 
Maclisp, since all Maclisp file arrays know tlicir charpos. Implemented by format- 
fresh -line, page 56, 

~X Outputs a space. ~«X outputs « spaces. No argument is used. 

~~ Outputs a tilde, outputs fi tildes, No argument is used. 

'^newline 

Tilde immediately followed by a carriage return ignores the carriage return and any 
whitespace at the beginning of the next line, With a the whitespace is left in place. 
With an @, Uic carriage return is left in place, 'I’his directive is typically used when 
a format control suing is too long to fit nicely into one line of tlie program; 

(format the-output-stream "~&This is a reasonably ~ 

long string~%") 

which is equivalent to formating tlie suing 

"~&This is a reasonably long string~%" 

~| Outputs a formfeed, ~n| outputs n formfeeds, No argument is used, 'fhis is 
implemented by format -formfeed, page 56, 

~T Spaces over to a given column, The full form is '^(ksHnatian JncrerrmilJ , which will 
output sufficicni spaces to move tlie cuisor to column (ic,stmiion. If the cursor is 
already past column destmatkm, it will output spaces to move it to column 
iksliiuuion ■¥ increment *k, for tlie smallest integer value k possible, increment defaults 
to 1, 'I’his is implemented by die format-tab-to function, page 56, 

"-0 ~Q uses one argument, and applies it as a function to params, It could tlius be used 
to, for example, get a specific printing function interfaced to format without defining 
a specific operator for that operation, as in 

(format t Tho frob ~vQ is not known. 

frob 'frob printer) 

'fl'c printing function should obey the conveiuions described in section 10.3. page 54, 
Note dial die function to ~Q follows die arguments it will get. bccau.se tiicy arc 
passed in as format parameters wliicli get collected betbre the operator's argument, 

~| is a set of alicmative control sirings. The aliernatiu's (called 

dmni's) are separated by -i and tlie •.onsinict Is lemiinaled by for es.nuplo, 
"-[Siamese ~;Manx ~;Persiaii ~;Toftoiae*Shtill ~;Ti(jor ~;Yu lluiainj "]kiUy", 
The orgih aliemaiive i-, selected; 0 selects the first. ]f a numciic parameier is given 
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(i.e. -«(), then the parameter is used instead of an argument (this is useful only if* 
the parameter is If arg is out of range no alternative is selected. After the 

selected alternative has been processed, the control string continues after the 

~lstr0'',sirl ~;.„~',slrn~: jiefaull~] has a default case. If the Iasi used to separate 
clauses is instead then the last clause is an "else" clause, which is performed if 
no other clause is selected, hor example, ’’~(Siamese ~;Manx '“;Per3ian 
~;Tortoise-Shell ~;Tiger ~;Yu-Hsiang ~i;Unknown ~J kitty". 

~['-iagOO,iagOI„.,',sfrO~hglO,.,.\strl...~] allows the clauses to have explicit tags. The 
parameters to each arc numeric tags for the clause which follows it. That clause is 
prcKCssed which has a tag matching the argument. If ,a2,bl is used, then 
Uic following clause is tagged not by single values but by ranges of values al through 
a2 (inclusive), bl tlircugh b2, etc. with no parameters may be used at tlie end 
to denote a default clause. For example, ’//;operator ~’A,’Z,'a,''z;letter 

~'0,'9;diglt ~:;other ~]". 

selects the fake control string if arg is nil, and selects the true 
control string otherwise. 

tests the argument. If it is not nil, tlicn the argument is not used up, 

but is tile next one to be processed, and the one clause is processed. If it is nil, then 

the argument is used up, and the clause is not processed. 

(setq prinlevel nil prinlength 6) 

(format nil PRINLEVEL=~D~]~@[ PRINLEN6TH=~D]" 

prinlevel prinlength) 

=> " PRINLENGTH=6" 

~R If tlicre is no parameter, then arg is printed as a cardinal English number, e.g. four. 
With the colon modifier, arg is printed as an ordinal number, e.g. fourth. With the 
atsign modifier, arg is printed as a Roman numeral, e.g, IV. With both atsigu and 
colon, arg is printed as an old Roman numeral, e.g. IlII. 

If tlicre is a parameter, then it is the radix in which to print the number. ITic flags 

and any remaining parameters are used as for the ~D directive. Indeed, ~D is the 
same as ~10R. The full form here is therefore ^ radix ,mincol ,pa(tchar,commacharB. 

~C arg is coerced to a character code. With no modifiers, ~C simply outputs this 
character, ~@C outputs the character so it can be read in again using the # re.jder 
macro; if tJiere is a named character for it, that will be used, for example 

"j«!<‘\Return": if not, it will be output like "^/A". ~;C outputs the character in 
human'i'cadablc form, as in "Return", "Meta-A". ~;@C is like ~;C, and 

additionally might (if warranted and if it is known how) parenthetically state how the 
character may be typed on the user’s keyboard. 

To find the name of a character, ~C looks in two places. 1hc first is the value of 
the symbol which is the value of format:*/^ -var, which is initiali/cd to be the 
variable which the ff reader macro u.scs. It is not necessary for the value of 

format; V ,'l<‘ var to be bound, 'Che second place is ‘format-chnames; this is used 

primarily to handle non-printing characters, in case tlic ^ reader macro is not loaded. 
Both of these are a-lists, of the form {(name . code) (name , code) 
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The Maclisp/NIL format has no mechanism for telling how a particular character 
needs to be typed on a keyboard, but it does provide a hook for one, If the value of 
format;* top -char -printer is not nil, then it will be called as a function on two 
arguments; the character code, and the character name. If there were bucky-bits 
present, then they will have been stripped off unlCvSs there was a defined name for the 
character with the bits present, llie fiinction should do nothing in normal cases, but 
if it docs it should output two spaces, and tltcn the how-to-type-it-in description in 
parentheses.' Sec section 10.3, page 54 for information on how to do output within 
format. 

~< ~mmcol,colinc,minpad,padchar<iexl~'> justifies lexl within a field mincol wide, text 
may be divided up into segments with the spacing is evenly divided between the 
text segments. Wjth no modifiers, tlic leftmost text segment is left justified in the 
field, and the rightmost text segment right justified; if there is only one, as a special 
case, it is right justified. ITic colon modifier causes spacing to be introduced before 
the fir.'.t text segment; the atsign modifier causes spacing to be added after die last 
minpad, default 0, is die minimum number of padchar (default space) padding 
characters to be output between each segment If the total width needed to satisfy 
these constraints is greater than mincol, then mincol is adjusted upwards in colinc 
increments, colinc defaults to 1, For example, 

(format nil "~10<foo~; bar~>” ) => "foo bar" 

(format nil "~lO:<foo~;bar'''>") => " foo bar" 

(format nil "~10 : 0<foo~ ;bar~>" ) => " foo bar " 

(format nil "~lO<foobar~>”) => " foobar" 

(format nil "~10:@<foobar~>") => " foobar " 

(format nil "$~10, , , ’ •<«-3f~>" 2.59023) => "$******2 . 69" 

If is used within a ~< construct then only the clauses which were completely 
processed are used. For c.xample, 

(format nil "~15<~S~;~''~S~;'-''~S~>" ’foo) 

=> " FOO" 

(format nil ’foo ’bar) 

=> "FOO BAR" 

(format nil ’foo ’bar ’baz) 

=> "FOO BAR BAZ" 

If the first clause of a ~< is terminated with instead of then it is used in a 

special way. All of tlie clauses are proce,sscd (subject to of course), but die first 
one is omitted in performing die spacing and padding. When the padded result has 
been detennined, dien if it will fit on the current line of output it is output and the 
text for the first clause is discarded. If, however, the padded text v.'iii not fit on die 
current line, dien the text for the first clause is output before the padded text, 'flic 
first ciau.se ought to contain a carriage return, 'I'hc first clause is always processed, 
and so any arguments it refers to will be used; the decision is whether to use the 
resulting piece of text, not v^lieiher to pmce.ss the first clause. If the has a 
numeric parameter a, then the |tadilcd text tmtst fit on the current littc with n 
character positions to spare to avoid uutputtitig the first clause's (ext. for example, 
the control string 
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"'“X:; "'(~<~X; : *”1:; ,~) .'*X" 

ciin ho used to print a list of items separated by commas, without breaking items over 
line bound.iries, and beginning each line with The argument 1 in ~1i; accounts 
for the width of tire conmia which will follow the justified item if it is not tire last 
element in the list, or the period if it is, If has a second numeric parameter, 
then it is used as the width of die line, thus overriding the natural line width of the 
output stieam. To make the preceding example use a line width of 50, one would 
write 

.~X" 

Note that the segments breaks tlie output up into arc computed "out of context" 
(that is, tiiey arc first recursively formatted into strings), 'Ihus, it is not a gotnl idea 
for any of tire segments to contain relative-positioning commands (such as ~T and 
<-&), or any line breaks. If is used to produce a prefix string, it also should not 
use relative-positioning commands. 

{sir -) 

This is an iteration construct, nic argument should be a list, which is used as a set 
of arguments as if for a recursive call to formal, rhe string sir is used repeatedly as 

the control string, liach iteration can absorb as many elements of the list as it likes. 

If before any iteration step the list is empty, then the iteration is terminated. Also, if 
a numeric parameter n is given, then there will be at most n repetitions of processing 
of sir . 

~',{sir~) is simitar, but the argument should be a list of sublists, At each repetition 
step one sublist is used as tlve .set of arguments for prcK'essing sir', on tire next 

repetition a new sublist is used, whether or not all of the last sublist had been 

processed. 

~@{j7r~) is similar to ~{.v/r~), but instead of using one argument which is a list, 
.ill the remaining arguments arc used as the list of arguments for Um iteration. 

~:@{sii'^) combines the features of and All the remaining 

arguments arc used, and each one must be a list. On each iteration one argument is 
u.scd ,is a list of arguments. 

Terminaiing the repetition constmet with ~;) instead of ~) foites sir to be piwesscd 
at least once even if the initial list of arguments is null (how'cvcr, it will not override 
an explicit numeric parameter of /,cro). 

If sir is null, then an argument is used as sir. It must be a string, and precedes any 
arguments puKcsscd by the iteration. As an example, tlte following arc equivalent; 

(apply (function format) (list* stream string args)) 

(format stream string args) 

This will use string as a formatting string. The ~1( says it will be priKcsscd at most 
once, ami the s,i\s it will be piwosscil at least once, rhereforo it is piwessed 
exactly once, using args as the arguments. 
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' ~) Terminates a It is undefined elsewhere, 

— This is an escape construct. If there are no more arguments remaining to be 
processed, then the immediately enclosing ~{ or ~< construct is terminated, (In the 
latter case, the ~< formatting is performed, but no more clauses arc processed before 
doing the justification. The -* should appear only at the beginning of a ~< clause, 
because it aborts Uic entire clause. It may appear anywhere in a construct.) If 
there is no such enclosing construct, then the entire formatting operation is 
terminated. 

If a numeric parameter is given, then termination occurs if the parameter is zero. 
(Hence is tlic same as ~#^.) If two parameters arc given, tennination occurs if 
they arc equal. If three arc given, termination occurs if the second is between the 
other two in ascending order. 

If is used within a ~;{ construct, then it merely terminates the current iteration 
step (because in tlic standard case it tests for remaining arguments of the current step 
only); the next iteration step commences immcdiatciy, 'I’o terminate the entire 
iteration process, use 

~F outputs arg in frcc-format floating-point. “hF outputs arg showing at most n digits, 
'“«:F will show exactly n digits. No other variations arc guaranteed at this time; 
neither is the exact interpretation of n. It is reasonable to use this, however, when 
one desires to print a llonum without showing lots of insignificant trailing digits; for 
example, 

(format nil "~6f" Z59. 258995) => ”259.269" 

~E Outputs arg in exponential notation; c.g., "2,59259e-r2". ~«E interprets n tlic same 
as ~F, No other parameters or flags arc guaranteed at tliis time. 

~$ (lliat’s a dollar sign,) ~rdigjdig afield, padchar% prints arg, a flonum, with exactly rdig 
digits after the decimal point (default is 2), at least Idig digits preceding the decimal 
point (default is 1), right justified in a field field columns long, padded out with 
padchar. The colon modifier says tliat we should cause the sig.i character to be left 
justified in the field. The atsign modifier says that we should always output tlic sign 
character. The Idig allows one to specify a portion of Uie number which docs not get 
zero suppressed. 

~\ 'ITiis is not really an operator. If one desires to use a multi-character format operator, 
it may be placed within backslashes, as in ~\now\ for the now operator. Sec page 

47. 
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10.2 Other Entries 

Tfornat destination control- string (Any-number-of/rofts) 

'i'his is equivalent to format except that destination is interpreted like the second argument 
to print— nil means "the default", and I means "the terminal". This only exists in 
Maclisp at the moment 

10.3 Defining your own 

daf 1n«-format-op Macro 

I'his may be used in two formats: 

(define- format-op operator varlist body-forms..,) 


and 


( def i ne - format-op operator fixnum-character-code) 

'fhe operator may be the fixnum code for a character, or a symbol with the same print- 
name as the operator. Whichever, it is canonicalized (into upper case) and will be 
interned into the same obarray/package which format resides in. E'or example, the format 
operator for tilde could be defined as 

( def i na-format-op /- #/~) 

where represents the fixnum character code for tilde. 

I'or die first format, the type of operator is determined by decoding varlist, which may 
have one of the following formats: 

(params-var) 

An operator of exactly zero arguments; params-var will get bound to the 
parameters list 

(params-var arg-vai) 

An operator of exactly one argument; params-var will get bound to the 
parameters list, and arg-var to Uie argument. 

(params-var . args-var) 

An operator of a variable number of args; params-var will gel bound to the 
parameters list, and args-var to the remaining arguments to format (or to the 
recursive arguments). The operator should return as its value some sublist 
of args-var, so tl'iat format knows how many were used. 

A definition for the appropriate function is produced with a bvl derived from the variables 
in varlist and a body of body-forms. ( Phe argument ordering in the function produced is 
compatible with that on the Lisp Machine, which is arg-var (if any) first, and then 
params-var, ) 

standard-output Variable 

Output from format operators should be sent to the stream which is tlie value of 
standard-output, In the Multics imploiucniation of format, this value may sometimes be 
an object which is not suitable for being fed to staiulard Lisp output functions (c.g„ 
princ): format lias (lofiniiions of various output functions which handle this case properly, 
and may be used for defining operators whicli will work c.anpatibly in Multics Maclisp. 
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'Fhey are documented below, Note that because of the way format interprets its 
destination, it is not necessarily safe to recursively call format on the value of standard - 
output in PDF- 10 Maclisp. It is safe, however, to use Tformat (page 54) instead, or to 
call format with a desUnalion of the symbol format. 

Maclisp format will also accept a destination of format to mean "use the format destination 
already in effect". This is primarily for the benefit of Multics Maclisp, since tlierc the value of 
standard -output cannot be passed around as a stream. Ihe format operator now, which prints 
the current time, could be defined as 

(define-format-op now (parains) 
params ; unused 

(let ((now (status daytime))) 

(format 'format "~2, '0D:~2, '0D:~2, ’OD" 

(car now) (cadr now) (caddr now)))) 

with the result that 

(format nil "The current time Is ~\now\,") 
could produce the string 

"The current time is 02:69:00." 

format: colon-flag Variable 
format :ats1gn-f lag Variable 

These tell whether or not we have seen a colon or atsign respectively while parsing the 
parameters to a format operator. They are only bound in tlic toplcvcl call to format, so 
are only really valid when the format operator is first called; if the operator does more' 
parameter parsing (like ~[ does) their values should be saved if they will be needed. 

ITiesc variables used to be named just colon-flag and atsign-flag, In the interest of 
transporting format code to Lisp implementations witli packages, tlicir names have been 
changed, 1'hu.s, in cither implementation one references them with the "format:" at the 
front of the name, which in Maclisp is just part of the print-name. 

The params are passed in as a list. This list, however, is temporary storage only. If it is 
going to be passed back, it must be copied. In Maclisp and NIL, it is an ordinary list which, in 
PDP-10 Maclisp, will be reclaimed after the operator has run. On the Lisp Machine, it will be a 
list-pointer into an art-q-list array, possibly in a temporary area. Thus, although it is safe to 
save values in tliis list with rplaca, one should not ever use rplacd on it, cither explicitly or 
implicitly (by use of nconc or nreverse). 

Conceptually, format operates by performing output to some stream, In practice, this is what 
occurs in most implementations; in Maclisp, there arc a few special SLAs used by format. This 
may not be possible in all implementations, however, To get around this format has a 
mcchani.sm for allowing tlic output to go to a pseudo-stream, and supplies a set of functions 
which will interact with these when tliey arc u.scd, 
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foriitt-tyo character 

tyos character to the format output destination. 

format-prlnc object 

princs object to the format output destination. 

fornat-prlnl object 

prints frob to the, format output destination. 

format-lcprinc string capitalize? 

'Hiis outputs string, which must be a string or symbol, to the format output destination 
in lower-case. If capitalize? is not nil, then the first character is converted to upper case 
rather than lower. 

fopmat-tarppi 

Does a terpri to the format output destination. 

fopfflat-^chappot 
format- 1 Inal 

Return the charpos and linel of the format output destination. Since in the Maclisp 
implementation multiple output destinations may be implicitly in use (via outfiles, for 
instance) this attempts to choose a representative one, 'fhe terminal is preferred if it is 
involved, 

fopmat-fpesh-llna 

'Phis performs the fresh -line operation to the default format destination. In PDF- 10 
Maclisp, this first will try tlie fresh -line operation if the destination is an SFA and 
supports it, Otherwise, if the destination is a terminal or an SFA which supports 
cursorpos, it will try (cursorpos 'a). Otherwise, it will do a terpri if the charpos is 
not 0. In the Maclisp implementation, where multiple output destinations may be 
implicitly involved (via outfiles, for instance), this handles each such destination 
separately. 

format-tai-to {dxnuM deslinaiton) {Optional increment?) 

'Phis implements ~T to the current format destination (q.v.), In PDP-IO Maclisp, this 
operation on an SFA will use tlic tab-to operation if it supported, passing in arguments 
of deslinaiion and increment (as a dotted pair); otherwise, charpos will be used to 
compute the number of spaces to be output. If charpos is not supported, two spaces will 
be output. 

format-formfeed 

Performs a formfeed on the format output destination. In Mullics Maclisp, this will 
normally just tyo tlic character code for a formfeed. In PDP-10 Miiclisp, this will use the 
formfeed operation if the destination is an Sl’A and supports it, otherwise it will do a 
(cursorpos ’c) if the destination is a TPY file array (or an SFA) and supports it, 
otherwLse it simply outputs tlic character code for a formfeed. 
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forniit-flate Macro 

( format-f late formi form2 ... formn) 

lltc forms arc evaluated in an environment similar to that used inside of format: tlic 
various format output-performing routines such as format -tyo and format -princ may be 
used to "perform output". In all but the Multics Maclisp implementation, standard- 
output will be a stream which simply counts the characters output— it wilt only support 
the tyo operation.' 

10,4 Format and Strings 

In the PDF- 10 Maclisp implementation, format has provision for using a user supplied string 
implementation, Normally, format expects to use symbols. However, if (fboundp ’stringp) is 
true, tlien format will use the stringp predicate to see if its argument is a string, If that is the 
case, then the function string-length will be used to find the size of lire string, and char-n will 
be used to fetch characters out of the string, Both of these routines should have been declared 
fixnum when compiled (i,e,, be ncallable). Internally, te.sts arc ordered such tliat string-ness is 
independent on atomic-ncss. In addition, the character routine may be used to canonicalize 
something to a character code. 

'nic Multics implementation is similar to the PDP-10 Maclisp implementation, but uses 
different routines; stringlength to get the size of tlie string (or symbol), and getchartr to fetch a 
character out of the string. The character routine is not used, 

•format-string-gensrator Variable 

This variable, which exists only in the Maclisp implementation of format, should have as 
its value a function to convert a list of characters to a "string" to be returned by format, 
In the PDF- 10 implementation, Uiis defaults to maknam, but may be modified if 
"strings" arc being supported. In the Multics implementation, it is a function which docs 

(get_pname (maknam character list)) 

and may be modified, if desired, to something more efficient. In the PDP-10 
implementation, the list of characters should neither be modified nor returned to free 
storage, as it will be reclaimed. 

The PDP-10 Maclisp hack of returning an uninterned symbol which has itself as its value 
and a + internal -string -marker property is not handled here; it is done by the outer call 
to format itself, and only if the returned "string" is a symbol and the value of ‘format- 
string-generator is maknam. This is done so as to not add unnecessary overhead to 
internal uses of "strings" by format. 

The name of this variable differs from that of other user-accessible format variables for 
historical reasons; it will not be changed, bccau.se it only cxi.sts in Maclisp. 
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11. System Differences 

lliis chapter describes differences you may encounter in using these tools in each of the 
various Usp dialects in which they have been implemented. One section is devoted to each 
implementation, and a final section deals with transporting code between them. The system- 
specific sections arc broken into parallel subsections. 

Since not all of tlic tools documented herein will be a part of Uic default Usp environment, 
the first subsection simply describes how to make tlicm available, 'nns will in general involve 
placing a form at the head of a source file to csLiblish tlic appropriate read-time and compile-time 
environment. 

The next subsection lists a number of things to watch out for in using a particular 
impiementation o; in writing transportable code. It deals with miscellaneous incompatibilities 
related to tliesc tools and to the Usp implementations in general. Some options which arc specific 
only to a single implementation arc documented here. 

'Fhc final subsection contains references to other sources of documentation, including that 
which is available online. 


lU PDP IO 

PDF- 10 Maclisp is currently in a state of flux with regard to how these tools arc provided and 
exactly where they arc kKatcd. Some arc present in the default environment while others must be 
requested explicitly. Check the online documentation for the current status. 

!1.U Where To Find It 

The sharpsign and backquotc reader macros arc present in tJic default environment, loop and 
format have autoload properties. Many of the functions and special forms described in chapter 8 
arc present natively or arc autoloadcd from. ((LISP) MLMAC ) (for MacLisp MACros). The rest 
may be loaded from ((LISP) UMLMAC) (for User MacUsp MACros). defstruct may be loaded 
from ((LISP) STRUCT). 

To use tlie bit -test, dolist, and dotimes macros, place the following fonn at the head of the 
source file. 

(eval-when (eval compile) (load '((lisp) umlmac))) 

To use defstruct, include tlic following form. 

(eval-when (eval compile) (load ’((lisp) struct))) 

This will cause defstruct to be present during the interpretation or compilation of a file. To use 
defstruct during debugging of the compiled file, sec section 9.6, page 40. 
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11 . 1:2 Things To Watch Out For 
dtfunli- chock -trgs Variabk 

rhc "extended defiin" facility (page 8) provides little or no argument count checking for 
functions by default. By setting this variable to t, the function being defined will contain 
additional code which will provide a more meaningful error message when the function is 
called with the incorrect number of arguments. 

A feature is provided whereby sequences of characters surrounded by balanced double-quotes 
are read as un-interned symbols which arc bound to tlicmsclves. 1’his provides partial 
compatibility with newer Lisps tliat have strings, fhey arc primarily useful as arguments to princ, 
load, and format, and arc not intended to be used as first-class data objects as on those systems 
which support them natively. 

11.1.3 Further Documentation 

For the latest changes to this implementation, sec the file .INFO. ;LISP RECENT on any ITS 
system. Earlier editions of this file arc archived in .INFO. ;LISP NEWS. The file .INFO, ;LISP 
FORMAT contains a chart of die format operators suimblc for printing on an ascii console, 'fhe 
files .INFO. I LISP LOOP and LIBDOC ; STRUCT > contain Uic Bolio source for the loop memo 
and die defstruct portion of this memo. Perhaps someday diese will be replaced by something 
formatted for a console. 

11.2 Multics 

T’hc Multics implementaUon is also changing, As of this writing, only some of dye extensions 
described in this document arc available from the standard libraries, but we expect the remainder 
to be insuillcd in die near future. Check die online drKumentation for the current status. 


U.2.1 Where To Find It 

Only a few of the improvements to Multics Maclisp since 1974 are now a part of the default 
environment. Primarily, diesc are die special forms which need to be primitively understood by 
die compiler, such as eval-when and unwind -protect and certain simple functions such as list*, 
'fhe special forms let and let* arc also in die default environment. The other tools d(x:umcntcd 
here may be accessed by die Multics Lisp special form %include. 'This form causes a text file to 
be inserted inline during the interpretation or compilation of a file, 'ITie form: 

(%include library) 

can be placed at the front of any file of Li.sp code that wants to utilize all of the features 
documented here, This form will arrange for the correct cval-iime, compile-time and run-time 
environments to be present whenever die file is being processed in any way, To arrange for diis 
extended environment to be prc.scnt whenever dic lisp iiUcrprctcr i.s being used, this fonu may be 
placed in die file star l_up . 1 i sp in the ascr’s home directory, 
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Since the %include form is unique to the MuUics implementation, a variant on the following may 
be used to allow the file to also read into other Lisps: 

(sval-^wben (aval compile) (or (status feature MuUics) (read))) 
(%inc1ude library) 

Ihosc MuUics Lisp users who wish to be more selective about the facilities they use may instead 
use the form 

(^include module) 

where module is one of backquote, sharpsign, defun, clef macro, defstruct, aetf, format, or 
loop, Selective loading of packages may be desired to prevent name or syntax clashes or to speed 
compilation, Note that some packages will load others as needed. For instance, defstruct will 
load setf. 

%include uses tlic translatoi search list to find Ute file to be included. To see the full 
pathname of the file which is found, type 

tthere_soarch_paths translator backquote. incl , lisp 

The actual object segments are bound together as bound_Visp_library_. 

where bound_1 isp_library_ 

will find the (till pathname of Uiis segment. 

'Hic modules listed above may be broken into three categories; read-time (backquote, 
sharpsign), compilc-time (defun, defmacro, setf, defstruct, loop), and run-time (format). 

'I'hc behavior of the include file for each module depends upon its type. For read-time and 
cornpilc-iime files, the include file will load the file at eval-timc or compilc-time, but will not add 
any forms to the object segment. For run-time files, Uie include file will place a form in the 
object scgnio.nl which will load the desired module, eitlicr directly or via an autoload property. It 
will also provide the appropriate ftuiction declarations for the compiler. 

1'o use an eval-timc or compilc-time module at run-time, you can type (%include module) to 
the interpreter or place tliis form in a file to be read into the interpreter, such as the 
start_up . 1 i sp file. Alternately, you can load tlic object segment directly, as in (load 
">exl>obiect>lisp_backquote_"), but this is not recommended since it requires specifying an 
absolute pathname. 

1 1.2.2 Things To Watch Out For 

The characlcre sharpsign ("#") and atsign ("@") are default erase and kill characters on 
MuUics, If these characters arc being used for input editing, you will have to type "\M” or 
"\@" to enter diem. Likewise, remember that to directly enter a backslash, two must be typed. 

Most other Lisp readers translate lowercase characters to uppercase characters in symbol 
names. The MuUics implonicntation <locs not do this case translation by default, This form will 
modify li'c rcadiablo to correctly read files which arc written in uppercase: 
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(do ((i r/a (1+ I))) 

((> I l/i)) 

(sotsyntax (- 1 4)o40) 

(bool* 7 (apply 'status (list 'syntax I)) #o500) 

D) 

Ilic syntax used for reading strings is also different from that used elsewhere, In other l.isps, 
the / character will quote the next character, so /" will insert a double quote character into a 
string. In Multics l.isp, the / character loses its special meaning and is interpreted as an ordinary 
alphabetic, fo insert a double quote character into a string, tire character is typed twice, 
following tlic Mitllics system convention, Phis incompatibility arose since tlic implementation of 
strings in Multics Lisp predated Uicir implementation elsewhere, 

While no installed facility is available at the moment for resolving tlicse syntax differences, 
the authors have a private reader which is compatible with tlic PDF- 10 ease and string syntax. 
Contact one of tlicm for more information, 

When tlic Multics Lisp compiler needs to generate an anonymous function, it creates a 
symbol to put tlic definition on. 'iliis will occur whenever a function is passed as an argument 
using (function (lambda or when using (defun {name prop) for example. 

Unfortunately, you get the same names every time you run tfie compiler. Doing 

(declare (genprefix unlcfue-name)) 

will fix this problem; tlic compiler will then use uni<iue-name as a basis for its generated names. 
For example, the loop module docs 

(declare (genprefix 1oop-iteration/|-)) 
so that tlic compiler will generate names loop- iteration/I -1, loop- iteration/I -2, etc. 

error works incompatibly. 'ITic second argument is output following the first, rather tlian 
before, as is done elsewhere. It is recommended tliat you use ferror instead, or define your o\ 
error signalling primitive, 'Hiis is often a good thing to do anyway. 

The default setting of the *rset switch is nit. You may find it helpful to turn it on in your 
start_up , 1 1 sp. 

If you find a symbol which has become mysteriously unbound, chances arc that you have 
taken the car of a symbol or bignum someplace, 'flic object returned by such an operation is the 
special marker stored in unbound value cells. 

'Die recently written Multics command display_lisp_object_segment (short name 
dlos) may be used to examine the contents of compiled Lisp object segments. It is quite useful 
in verifying the proper execution of complex macros and compile-time f/cilitics. 


MI,;MAnxu :l)in s Ifi 


21-.IUI -St 



Lisp Machine 


62 


Maclisp Kxtcnsioni 


11.2.3 Fuu r Documentation 

Online Lisp documcniation resides in the directories >«x1>lnfo and >doc>info. 'Oic info 
segment lisp, changes, info describes the latest changes to the Multics implementation. 
1 i.sp„manua1_update , info describes earlier changes. A collection of segments 
lisp_m(a/M/c,info, where module is as above, repeat the documcnuitioo contained in this 
manual, Tinally, Ujc segment di splay_l i sp_objoct_segment , ’/nfo describes the 
di splfiy_l 1sp_objact_segm«nt command. 

'Hiese segments may be perused by means of the help command, For instance, type 
*'he1p 1 i sp , changes" to view the first of these segments, 


11.3 Lisp Machine 

On the Lisp Machine, everything described in this document is a part of tlie default 
environment, No changes need be made to source files. 

Further documentation may be found by consulting the Lisp Machine Manual, the LMMAN 
directory on the A1 machine, and finally the source code itself, 'fhe /.macs command Meta- 
period will prompt for a function or variable name and read tlie source file in which it is defined 
into a buffer, 

1 1.4 Hints Oil Writing Transportable Code 

Phis section contains some hard-knocks knowledge gathered by the authors over many tea- 
filled nights of grief. While we have done our best to distill some coherent advice from our 
experience, there are no easy answers. This is at times a black art 

No doubt tlierc arc techniques (and pitfalls!) which we have overlooked. If you have 
something which could be added to this section, the authors would like to hear from you. 


11.4.1 (onditionali/ation 

Ultimately, despite everyone’s best efforts, you arc likely to find tliat your code must be 
conditionali/ed in .some manner, In this eventuality there are a couple of things to be aware of, 

The sharpsign reader macro (chapter 3, page 5) is a very handy tool for conditionalizing code 
for diflorcnt sites, However, its indiscriminant use can result in highly unreadable code, 
Frequently, when it seems tliat conditionali/ations arc going to need to be sprinkled throughout a 
piece of code, it is possible to identify a common pattern between Uicm, and replace them with 
an appropriately defined macro. I'his macro will have a definition that will be conditionalized for 
each site that the code runs, and will serve to localize the ugly implcincniation dependent details. 
Sometimes tins operation actually improves the readability of the code, since it forces the 
programmer to give a name to a pattern present in many places, 

As an example, the following macro provides a , system-independent way of determining the 
screen size of a console stream. 
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(dsfmacro sersan-stz* (stream) 
f^ITS '(status ttystza .stream) 
tlt-r^Lispm '(multiple-value-bind (width height) 

(funcall .stream ’ i size-in-characters) 

(cons height width)) 

(|f-(or ITS Lispm) "(80. . 24. )) 

Another problem with using any of tlic conditionali/ntion features of the sharpsign reader 
macro is tire fact that although something like 

form 

does cause the fomi form to be ignored in l isps that aren’t of the Nil. variety, it is nevertheless 
necessary tliat form be readable in those oilier Lisps, In other woids, if form contains Uie use of 
a reader syntax iliat is only supported in NIL, tlicn it won’t wojk to conditionali/c form in this 
manner, because other Lisps are going to have to parse it, 

Currently, a frequent cause of such problems is tlic use of a special character name alter ^ \ 
that isn't universally understood. 

In some situations, large portions of a program will need to be written differently from system 
to system. Often such portions will deal with issues of operating system interface, such as console 
or file i/o. In such cases, it is best to define a common interface to iliis portion, so that this 
code may be factored out into separate files, 

11.4.2 Odds and Ends 

Avoid directly inserting into your code constants which arc specific to the byte, word, or 
pointer si/c of a machine. For instance, use (rot 1 -1) instead of 1_43 to reference Uie most 
negative fixnum on a P1)F-10, Similarly, use (Ish -1 -1) for Uie most positive fixnum and 
(haulong (rot 1 -1)) for Uie number of bits in a fixnum, 

'fhcrc is only one reliable way to define a function Uiat ignores one or more of its arguments 
without complaint from Uie compiler: 

(defun i gnora-secord-arfj (first second third) 
second {ignored 

(list first third)) 

Other conventions do not work universally. 

Not all Lisps have strings. However, in most, text surrounded by doublcquotcs will read in 
as some kind of object which will print out again in a readable formal, This object is suitable for 
passing to functions such as princ and format, but cannot be universally guaranteed to behave 
reasonably with functions such as equal. 

In Maclisp, Uie dcfaiilt syntax of the colon character is alphabetic, but it has special meaning 
on Uie Lisp Machine, Don’t use it in the name of a symbol unless you know what you are 
doing. 
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If colons arc being used only for denoting keywords, then it is useful to give colon the syntax 
of whitespace outside the Lisp Machine. This can be accomplished with this Maclisp form: 

( setsyntax * j : | ' | | nil) 

Don't leave control-V's (circle-plus on Uic Lisp Machine) lying around randomly, like in vairct 
strings, Ihcy have special syntactic meaning on the Lisp Machine. 

All PDP-10 Maclisp compiled output ("FASL”) files use the same format. It is therefore 
possible to transport the compiled file between PDF-lOs (c.g,, from an I'l'S to a TOPS-20), if the 
code contained dicrcin is not conditionalizcd on those differences. The source code for loop, for 
example, docs not contain any ^ or # - conditionalizations which distinguish between any 
PDP-IO implementations; dtc FASL file for loop used on 'fOPS-20 and TOPS-10 sites is the same 
one used on ITS. 
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